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Ms.v0s Papers is the latest in The Waite Group's contributed series on pro- 
gramming languages and operating systems. This particular collection of essays 
focuses on the MS-DOS operating system and brings together a far flung variety 
of MS-DOS programmers. In choosing these essays, we have strived to reflect the 
real world of MS-DOS programming rather than the more traditional approach 
of textbooks and software manuals. Thus, you will find in this book subjects not 
usually covered, in a way not usually found, in the trade literature: 


> secrets and tricks of coding 
r> use of MS-DOS internal structures 
=> tools 


=* utilities 


None of the original designers of MS-DOS expected it to be used for a wide 
variety of applications, nor could they have anticipated the needs that users now 
present. In the early 1980s, the designers revised the system by providing new 
functions, interrupts, and other internal services, and they protected their revi- 
sion process by secrecy and documentation that often offered no more explana- 
tion than “reserved.” But give them credit for a good design! MS-DOS has 
survived tremendous changes, although to a large degree the operating system 
itself has become something of a kludge—a set of patches, fixes, device drivers, 
and add-ons. And all the while, application programmers have been busy disas- 
sembling, uncovering, and sharing the mysteries one by one. 

Although the operating system is now quite mature, the revisions to 
MS-DOS are coming more slowly, while the market is screaming for more perfor- 
mance. New generations of software need more than 640K memory, higher res- 
olution graphics, faster calculations, and multitasking on a single-tasking 
system. Obviously MS-DOS has hit a performance wall. In order to answer these 
new market demands, enhancements are coming not from further improve- 
ments of the operating system internals but from external sets of ad hoc conven- 
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tions that define such standards as Expanded Memory Specification (EMS), 
Enhanced Graphics Adapter (EGA), and Terminate and Stay Resident (TSR) pro- 
grams, and such extensions as device drivers and C libraries. 

So long as MS-DOS continues to flourish in this “pruning” and “patching” 
way, MS-DOS programmers must learn to work outside of the operating system 
as well as within it. This means learning not only the standards of EMS, EGA, MS 
Windows, and other external environment additions, but also the conventions of 
programming lore—which registers to use, which functions to call, how to 
share the use of system services with unknown applications, how to test the IN 
_DOS flag, upper interrupt areas (INT 60H to 67H), PSP, and other MS-DOS data 
structures. For example, if different applications are to share memory, the pro- 
gram designers must agree on the allocation and use of that common memory 
space, or one program may write over the other. As another example, program- 
mers must know how to test for, save, and restore any existing screen contents if 
their application is to overwrite an area of the display. To make the point, a TSR 
program that disables other TSRs, or that overwrites a screen and then disap- 
pears without restoring that previous screen, is likely to get poor recommenda- 
tions from disgruntled users. Anticipation of possible problems and awareness 
of well-behaved manners are critical to a designer's ability to create a successful 
MS-DOS application today. 

In the increasingly complex MS-DOS operating system environment, many 
programming rules, conventions, and good manners are shared by word of 
mouth, over telecommunications networks, and in special journals. We have 
tried to capture much of this hard-to-find lore inside this book. We have asked 
the authors to explore what MS-DOS areas they know best. It is our hope that 
you find this a readable, rich collection of wisdom that adds to your experience 
and skill as an MS-DOS programmer. 
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L the course of studying programming in MS-DOS, you may have noticed that 
people seem to have markedly different approaches, even to the point of contra- 
diction. Indeed, one quickly discovers that the MS-DOS world is one of short-cuts 
and trickery of remarkable range, where anything that works is fair game. Find- 
ing these important tricks, insider techniques, and bottom line facts is extremely 
tedious because they are spread out in so many places—from technical net- 
works to obscure articles in programming magazines. The Waite Group's 
MS-DOS Papers brings you the most important of these ideas, tips, and tech- 
niques in a single reference source. 

Our purpose in this collection of essays on MS-DOS programming is to cre- 
ate a forum for many professional points of view so that you can pick and choose 
among techniques and inspect the major advanced extensions of MS-DOS 
through many different windows. This is not a training book showing users how 
to use MS-DOS; rather, the essays in this book show programmers how to arm 
themselves to manipulate the operating system and to write better performing 
software. As usual, speed is a major goal, so many of these essays reveal slick 
techniques to speed up the user interface and access hardware. If you have any 
interest in understanding the inner workings of the MS-DOS operating system, 
this book is for you. 

The Waite Group’s MS-DOS Papers is divided into three topic areas: 


<> sophisticated use of the user interface (manipulating directory struc- 
tures, using libraries and batch files) 


= techniques for programming (working with functions and internal data 
structures of the operating system to control application programs such 
as Terminate and Stay Resident programs) 


YY 


> control of the system hardware (understanding interrupts, functions, 
and data structures to manipulate hardware such as the serial port, En- 
hanced Graphics Adapter, Enhanced Memory Specification, and more) 


It goes without saying that MS-DOS programmers must be fluent in both 
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the C language and assembly language, especially MASM 5.0. They must be fac- 
ile users of the compilers and software development tools. Indeed, much of the 
work programmers do is spent setting up their systems for maximum efficiency. 
They must be practiced users of the operating system’s commands and underly- 
ing environment. These skills are the focus of essays in the first section. 

MS-DOS programmers must contend with an increasingly extended envi- 
ronment, and this is the background for the second and third sections. MS-DOS, 
despite its age, is still growing and expanding, so most MS-DOS systems are be- 
ginning to suffer from overpopulation of large application programs, memory- 
resident programs that are squeezing the interrupt system, and constraints of 
managing huge amounts of data. The effect is that after several major revisions, 
the MS-DOS operating system has reached a state of maturity that now requires 
working programmers to be familiar with all the system's interrupts and func- 
tions and several sets of services beyond those of MS-DOS itself. 

Essays in the second section deal with understanding undocumented func- 
tions, learning to write Terminate and Stay Resident programs that work pre- 
dictably without interfering with other applications also loaded in memory, 
creating data protection and encryption schemes for file security, and inspect- 
ing the behavior of the MS Windows operating environment. 

Essays in the third section focus on hardware—how to write device drivers, 
control the serial port, program high-resolution color screens controlled by the 
EGA display cards, and use large amounts of memory provided by the EMS hard- 
ware and software. 


This Book and Other Waite Group Books 


The Waite Group’s MS-DOS Papers is a follow up to other Waite Group books: MS- 
DOS Developer's Guide, a detailed examination of the MS-DOS operating system; 
Tricks of the MS-DOS Masters, a collection of techniques for advanced users; MS- 
DOS Bible, a complete reference book with tutorials for intermediate users; and 
Discovering MS-DOS and Understanding MS-DOS, both of which are introduc- 
tions to the MS-DOS operating system for beginners. 


What You Have to Know to Read MS-DOS Papers 


XVvill 


You must, at a bare minimum, know how to operate MS-DOS well enough to 
copy files between subdirectories, install drivers and other commands in the 
CONFIG.SYS file, and use the standard internal and external commands. You 
must also understand generally how the 8088/86 central processing unit (CPU) 
works, the limitations of the MS-DOS 640K memory scheme, and the relation- 
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ship between peripheral devices, ports, and the I/O channel slots. Building upon 
this basic knowledge, you will learn what structures make up MS-DOS and how 
they behave and gain an understanding of modern enhancements to the system. 

Intermediate programmers, with professional user-level skills and some 
knowledge of either assembly language or the C programming language, will 
find useful details of MS-DOS services as well as usable program listings with 
complete explanations of the design of the code. 

Advanced programmers, familiar with both 80X86 assembler and C as well 
as MS-DOS system calls, have in this book a sophisticated treatment of many of 
the important topic areas that underlie the major marketing features of modern 
applications, namely, control of the Enhanced Graphics Adapter (EGA), use of 
Expanded Memory Specification (EMS), operation of memory-resident pro- 
grams (TSRs), examination of the Microsoft Windows operating environment, 
and much more. 


Organization of MS-DOS Papers 


MS-DOS Papers begins with an overview of the inner structure of MS-DOS, fol- 
lowed by sections that roughly parallel the three conceptual areas of MS-DOS 
itself: the user interface shell; the kernel; and access to hardware through the 
BIOS, ports, and device drivers. The following is a description of the essays in 
this book. 


Section One: Extending the MS-DOS User Interface 


MS-DOS is composed of three modules: the user shell COMMAND.COM; the kernel 
and the main services, MSDOS.SYS; and the hardware access routines 10.SYS. This 
division provided the inspiration for the section divisions of this book. The fact 
of this modularity of MS-DOS has allowed for the upgrade of each module with- 
out respect to the others and also for manipulation and even replacement of one 
of the modules without disturbance to the others. 


A Guided Tour inside MS-DOS 


Essay 1 offers a rare, comprehensive overview of the insides of MS-DOS with 
suggestions for modifications for increasing user-level speed and functionality. 
Of special note, this essay contains a great number of references to the other 
essays in this book and serves to tie all of the papers together. 
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Searching the File Tree with whereis 


The MS-DOS file system is built around a hierarchical file system of directories 
and subdirectories, yet it does not include a feature with which to find and act 
on a file without first setting a PATH specification or invoking the correct sub- 
directory. In other words, in order to find a file, first you have to know where it 
is—not good. Essay 2 presents a search tool written in C called whereis. The 
whereis utility combines two essential features: the ability to search for match- 
ing files within the whole file tree (not just within one directory) and the ability 
to use MS-DOS commands or programs to manipulate the files it finds. 


Adding UNIX Power with PCnix 


PCnix is a homespun set of public domain utilities, batch files, and imaginative 
patches that augment the MS-DOS A> prompt interface. By adding PCnix to your 
MS-DOS system, you get such UNIX-like features as command-editing and a “his- 
tory” capability to the MS-DOS user interface, the use of UNIX syntax, and a tool- 
kit of UNIX-style commands for managing files and text. Essay 3 presents a 
highly entertaining description of the process of tweaking interrupts and “fool- 
ing DOS’ to attain important UNIX-like power while preserving MS-DOS compat- 
ibility. PCnix is available on three diskettes. 


Adding Power to MS-DOS Programming 


The first order of business for a professional C programmer is to set up applica- 
tions and files for fast, easy access. This means developing a library of routines 
and having a way to invoke them quickly. Essay 4 examines a popular third-party 
interface extension, Enhanced Batch Language (EBL), a powerful batch language 
facility with increased variables and commands, as well as two C library pack- 
ages, the C-INDEX, which provides detailed file-search capabilities, and Vitamin 
C, a set of library routines that automate the creation of screens and windows 
and provide B-tree file indexing. 


Advanced MASM Techniques 


Nearly all working programmers must use assembly language at least occasion- 
ally, and yet, constructing a program at the machine instruction level is painstak- 
ing at best. It's easy to lose track of bits, frustrating to retype code, and tedious to 
construct database records and fields. Essay 5 examines features of Microsoft's 
Macro Assembler (MASM) version 5.0 from the standpoint of using names to set 
up and control bits within a byte and bytes and words within data structures. It 
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explores the uses of directives, Macros and subroutines (and when each is ap- 
propriate), how to handle hardware interrupts, and more. 


Section Two: Programming Tools and Techniques 


While Microsoft and IBM have discouraged use of many “undocumented” serv- 
ices within the operating system, the programming community has relied on 
just those services to push performance to the limits. Essays in this section focus 
on how to work with the operating system itself. 


Undocumented MS-DOS Functions 


Essay 6 explains the Program Segment Prefix (PSP), a data structure that 
MS-DOS creates and loads as a header to .COM and .EXE programs. It then 
shows how to: use file handles to customize redirection; access and manipulate 
the environment segment from batch files; use PSP function calls from within 
TSRs; allocate and deallocate memory; inspect the Memory Control Block chain; 
and get MS-DOS busy flag, switch char, DOS variables, and more. 


Safe Memory-Resident Programming (TSR) 


Terminate and Stay Resident (TSR) programs (known to many users as “popups’) 
have come into respectability despite their use of undocumented functions. Essay 
7 discusses the skills of safe TSR design that have become a staple in many work- 
ing programmers’ bags of tricks. It begins with a history of TSRs in CP/M, 86-DOS, 
and MS-DOS, then describes problems in handling hardware and software inter- 
rupts, noting differences between INT 27H (terminate but stay resident interrupt, 
originally used in 86-DOS), INT 21H Function 31H (Keep Process Call, first used in 
MS-DOS 2.X), and INT 2FH (Multiplex Interrupt, developed in MS-DOS 3.X). Also 
included is discussion of how to use INT 21H Function 34H (IN_DOS Flag Call), 
INT 28H (background process function), and INT 21H Function 50H (how to save 
the PSP of the foreground program), all of which allow multiple TSRs to exist in 
memory. Finally, there is an examination of the TSRs provided with MS-DOS: 
GRAPHICS, ASSIGN, and PRINT utilities. You'll also find a TSR to toggle the print 
screen function and a review of the newest Microsoft TSR guidelines. 


Data Protection and Encryption 


Data protection, meaning protecting your data from loss or unauthorized en- 
croachment, is often ignored by the application programmer or implemented as 
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an afterthought. Essay 8 provides a complete tutorial on MS-DOS data security 
programming techniques. You see how each programmer can hide data by using 
nonstandard names and characters, by using an assembly language program to 
toggle the hidden attribute, and by using the read-only attribute. The author 
shows how to use a password protection scheme in the AUTOEXEC.BAT file, in a 
device driver, installed on an add-on card, or with a TSR to capture INT 21H calls 
to verify password status. Finally we see how to encrypt the data itself by using 
code book, keytape, and DES and RSA key algorithm systems. 


Inside Microsoft Windows 


The Microsoft Windows operating environment, after several years of develop- 
ment, extends MS-DOS functionality into the complex and powerful realm of 
multitasking and windowing similar to the Macintosh and OS/2 systems. Essay 9 
introduces the major programming concepts of MS Windows, messages, and 
queues that make for an event-driven, modeless environment. It illustrates the 
message stream from the mouse, keyboard, and other software sources and 
shows how to use Windows functions to manipulate that stream. It explains new 
concepts and terms such as overlapping and popup windows, child windows, 
classes, coordinate systems, regions, memory management including global and 
local heaps, resources, and the new Windows functions that are associated. It 
also presents complete explanation and source code for an examination utility 
that traces through running Windows applications and reports back details on 
their behavior and resources. 


Section Three: Working with the Hardware Interface 


XXii 


The five essays in this section focus on controlling the hardware environment 
and extracting the maximum speed from RAM memory, board-level registers, 
and MS-DOS services. 


Developing MS-DOS Device Drivers 


Device drivers are the critical software between custom hardware and applica- 
tions that run under the operating system. The key to programming successful 
device drivers lies in knowing what MS-DOS services come into play and how 
they work. The trouble is this involves nearly all MS-DOS kernel internal struc- 
tures, which makes a tangle of relationships and a need for a half-dozen books, 
tables, and manuals. Essay 10 presents all the workings of these MS-DOS data 
structures: stacks, the System File Table, File Control Blocks and file handles, 


Introduction 


Device Control Blocks, Current Directory Structure, Program Segment Prefix 
with the device driver strategy, and interrupt structures. The author uses a 
small applications program that simply lists a file at the console to exemplify the 
basic kernel behavior. As the essay progresses, the author shows such details as 
checking both the IN_DOS flag and the critical error flag to avoid disrupting 
non-reentrant procedures, using file handles instead of the File Control Block, 
using IOCTL requests, and more. 


Writing a SOUND Device Driver 


Following the previous essay on device driver theory, Essay 11 explains the oper- 
ation of a real-world device driver that lets an operator use the PC for manipulat- 
ing tones, sounds, and special effects. This sophisticated driver mimics the 
BASIC PLAY statement down to its detailed command language. The driver code 
depends upon such computer science concepts as circular buffers, coroutines, 
finite state machines, and more. In its simplest form, you can create a file com- 
posed of commands for the driver, then copy the file to the driver. With just a 
small amount of additional code, you can open the device from within an appli- 
cation, then write to it, thus playing a tune from within your spreadsheet, word 
processor, data capture application, or whatever. The essay concludes with a 
complete listing for a driver named SOUND. 


Programming the Enhanced Graphics Adapter 


The resolution offered by the Enhanced Graphics Adapter (EGA) is the current 
preferred standard for color displays. But program control of the EGA is mark- 
edly different from that of its predecessors, especially in the way in which one 
keeps track of writes and rewrites to the registers. Essay 12 begins with a thor- 
ough discussion of the EGA, its registers, and its latches. After showing how to 
use macros to control the bit mask and map mask, the author presents a very 
fast line-drawing routine based on Bresenham'’s algorithm, a macro PEEK and 
POKE directive, a hard-to-find dithering algorithm for a laser printer, and more 
techniques to write colored images to the screen. The author also shows how to 
read the EGA memory and how to use the EGAs data rotate register to perform 
Boolean operations on the EGA bit maps. 


Programming the Serial Port with C 
The serial port has become overloaded with peripherals—mice, pads, and cam- 
eras, as well as modems and printers. It is no wonder that control of the serial 


port is a chief target of concern of hardware programmers. Essay 13 begins with 
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a complete, fast-moving overview of the conventions of serial data flow and 
shows how to control the serial port hardware, including the UART and a mo- 
dem. The discussion covers error-checking, flow control, buffers, and use of the 
8259 to manage the serial adapter interrupts, and ends with discussion of a cir- 
cular data buffer. Finally, the author offers an explanation of commented source 
code in C for a complete communications package. 


Understanding Expanded Memory Systems 


Expanded memory systems depend on a scheme of switching various banks of 
memory in and out of the 640K MS-DOS main memory address structure de- 
fined by MS-DOS. The bank-switching process is controlled by a driver called the 
Enhanced Memory Manager (EMM) designed by Lotus, Intel, and Microsoft. Es- 


.Say 144 shows how the EMM behaves and notes differences between the three 


existing systems: Expanded Memory Specification (EMS) version 3.2, EEMS (the 
extra E for Enhanced), and EMS version 4. The essay begins with a discussion of 
bank-switching and the genesis of EMS. It then shows two ways to test for the 
presence of an EMS device. The first uses Function 3DH (open file or driver- 
request) specifying the guaranteed name, EMMXXXXO, then uses subfunctions 
of Function 44H to check further. The second uses INT 67H to check for the 
ASCII string of that same guaranteed name. The author includes a table of error 
codes, a summary of relevant functions for both EMS 3.2 and EEMS, a simple 
eight-step strategy for using EMS, and much more. 


Disks Available 


Some authors are offering disks with source code; ordering information is given 
at the end of Essays 3, 8, 11, and 13. 


Inside the Book 


Each essay begins with a synopsis and a list of keywords, and ends with a biogra- 
phy of the author and a list of related essays. As noted earlier, within each essay, 
where appropriate, you will find references to other essays. The purpose is for 
you to determine your own reading path through the book. 

We suggest that you begin with the first essay, “A Guided Tour inside 
MS-DOS’ (by our editor Harry Henderson). In this essay, Harry mentions all the 
other essays within the book as he explores the internal operations of the MS-DOS 
operating system. From there you can jump to essays that meet your interests. 


Section One 


EXTENDING THE MS-DOS 
USER. INTERFACE 
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The MS-DOS operating system, depending on which version you may be us- 
ing, provides roughly two dozen internal commands that allow only the most 
elementary inspection and manipulation of files and directories. Its accompany- 
ing utility programs, otherwise known as the external commands, provide suffi- 
cient power for necessary housekeeping, but in a painfully inelegant manner. 
Using the MS-DOS system by itself, a programmer must work slowly, chore by 
chore. At the operator level, the MS-DOS operating system provides just enough 
capability to load and run application programs and store their files. It seemed 
like a good system at first, but most active users have outstripped it, as a young- 
ster outgrows a pair of pants. 

Working programmers, especially, must develop a flexible set of tools to 
manage complex file relationships and to invoke a rapid succession of utilities. 
Most programmers have developed a colorful mix of third-party patches—some 
of their own invention, some from bulletin boards, and some from the pages of 
magazines—to fill the gaps of a user interface that seems increasingly inade- 
quate. The artful use of batch files shows the skill with which inventive minds 
can bootstrap the limitations of the batch file commands. An inspection of an 
extensive CONFIG.SYS file reveals the soul of system flexibility with a list of names 
that are as technical and arbitrary as the cards that sit in the internal slots of the 
machine. 

This section of MS-DOS Papers contains five essays illustrating the authors’ 
creations for improving the limited features of the MS-DOS user interface. 


A Guided Tour inside MS-DOS 


The first essay, by Harry Henderson, introduces you to the inner structure of 
MS-DOS. It is a rare overview with suggestions for increasing user-level speed 
and functionality. The author also includes many references to all the other es- 
says, thereby tying together the entire book. 
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Searching the File Tree with whereis 


In the second essay of this section, Frank Whaley explains how he created a 
powerful file and subdirectory finder, whereis, written in C, that lets you search, 
match, and manipulate files using MS-DOS commands. 


Adding UNIX Power with PCnix 


Ed Nather presents a wild set of utilities and routines that provide an expansive 
UNIX-like environment, with command editing, file and directory manipulation, 
and a running commentary explaining a slightly topsy-turvy view of the MS-DOS 
interrupt and function scheme. 


Adding Power to MS-DOS Programming 


The fourth essay, by Doug Adams, presents a quick overview tutorial of the use 
of the Extended Batch Language (EBL) utility and C libraries that streamline 
mundane programmer's chores such as the creation of menus, windows, in- 
dexed files, and more. 


Advanced MASM Techniques 


In the fifth essay, Michael Goldman shows us tricks to using MASM 5.0 labels, 
directives, and macros to reduce bit-level errors and speed data constructs as 
well as to handle hardware interrupts. 


Keywords 
user interface 
MS-DOS kernel 
BIOS 
MS-DOS file system 
programming environments 


commands and utilities 


Essay Synopsis: MS-DOS has three ba- 
sic parts: a user interface (normally pro- 
vided by COMMAND.COW),.a system kernel 
containing data structures and function 
calls needed by programmers, and.a hard- 
ware-oriented BIOS. This essay points out 
the significant features of MS-DOS at each © 
of these levels, and highlights the strengths 
and weaknesses of each for power users 
and programmers. MS-DOS is more than 


just an operating system, however. It is also 
an environment that can be expanded‘and 


customized by the addition of new shells, 
utility programs, programming environ- 
ments, and device drivers. This essay shows 
how these products can be used to over- 
come many of the shortcomings of MS-DOS, 
and explores current and future trends in 
MS-DOS use and programming. 


A Guided Tour 
inside MS-DOS 


Harry Henderson 


Mss.v0s has many faces—like the fabled elephant, it can look very different 
depending on one’s point of view. Users need to be able to configure their envi- 
ronment, set up their applications programs and programming tools, and man- 
age megabytes worth of directories and files. Applications programmers must 
learn how to use the many MS-DOS system services that their programs need to 
manage system resources. Many of these services are poorly documented, and 
many rely on an understanding of internal DOS tables or data structures. Sys- 
tems programmers need to write device drivers to enable programs to use a 
new printer or mass storage device. In addition, programmers frequently need 
to learn specialized programming interfaces such as those for the serial port, 
Enhanced Graphics Adapter (EGA), Expanded Memory Specification (EMS), or 
Microsoft Windows. 


The Challenge of Change 


MS-DOS programmers live in a complicated and ever-changing world. Those 
who want to be competitive must keep one eye on today’s needs and the other on 
those of the future. Consider the life cycle of a simple application program. 
Beginning as one programmer's “quick and dirty” tool for performing some cal- 
culations, the program is given to a team whose mission is to turn it into a com- 
mercial product. The original program provided only a text display, but the 
marketing department convinces the programmers that there is a demand for 
color graphics. The IBM Color Graphics Adapter (CGA) display doesn’t provide 
enough resolution or colors for most graphic needs, however, so it’s time to learn 
how to program the EGA. 

The first version of the product is marketed. Users quickly request more 
features—such as the ability to move from writing a report to calculating a 
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spreadsheet to consulting a database, with instant access to any or all of these 
features. Now we have an “integrated software package,’ but the users are com- 
plaining that the program takes up too much memory and doesn’t allow them to 
run their favorite memory-resident utilities. It's time to learn how to break the 
“640K barrier” imposed by DOS, by using EMS to handle larger amounts of data 
and conserve precious space in main memory. Next, the users say they want Post- 
Script output and the ability to use a new laser printer. Oh, and by the way, 
larger customers are starting to ask when the network version will be ready. It's 
time to learn everything about device drivers. 

Now the program is powerful but it’s hard to use. Perhaps it should be re- 
written to run in the Microsoft Windows environment, and provide a graphic 
user interface, and update the spreadsheet every time a change is made in the 
database... 


Overall Structure of MS-DOS 


Before we can find out how to improve MS-DOS and our programming environ- 
ment, we have to understand its design and the way its parts fit together. 

There are three modules that make up MS-DOS: the user shell, the system 
kernel, and the hardware interfaces, including the Basic Input-Output System 
(BIOS) routines. 

MS-DOS is, at bottom, a program loader and file handler with roots in the 
CP/M operating system developed in the late 1970s. MS-DOS has, of course, be- 
come much more than that after going through two major (and numerous mi- 
nor) revisions since Microsoft and IBM first made it available in 1982. It has had 
to accommodate hard disks and other new storage media, RAM disks, new dis- 
play standards, mice, memory-resident programs, expanded memory, and net- 
works, to mention just a few of the developments. 

The most important aspect of the structure of MS-DOS is its modularity. 
The division of MS-DOS into three parts—a command processor, a system ker- 
nel, and a hardware-specific BIOS—is what has made it possible to add features 
in response to the development of new hardware, and to accommodate the dif- 
ferences in the underlying hardware of PC clones and compatibles. Because only 
the BIOS module is hardware-dependent, the user interface and system kernel 
do not have to be revised to accommodate new hardware. 

MS-DOS contains a standard character-oriented user interface that is sim- 
ilar to those found on most mainframe operating systems. Because this interface 
is a separate module, however, it can be replaced or supplemented with a differ- 
ent one such as Microsoft Windows or a UNIX-like shell. 

The MS-DOS kernel contains the compiled code for the internal services 
(such as file management and I/O) needed to execute both MS-DOS commands 
and applications programs. This kernel is essentially hardware-independent, so 
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a hardware vendor does not need to rewrite it to get MS-DOS to run on a new 
machine. Furthermore, the installation of new devices requires only that a de- 
vice driver be written and linked into a list of drivers maintained by the kernel. 

Finally, the BIOS contains the hardware-specific code, the code that deals 
with devices on a low level. Because the hardware details are hidden from the 
rest of the operating system, additions at the BIOS level make it possible to add 
support for new devices, such as hard disk support in MS-DOS 2.X and support 
for 720K 312" floppies in MS-DOS 3.2, without having to make extensive changes 
to services in the kernel. 


System Files and DOS Modules 


The MS-DOS distribution disk provides the operating system itself in the form of 
three files that correspond to the three modules or interfaces that we have men- 
tioned: 


COMMAND.COM, a program that provides the standard MS-DOS user inter- 
face and a prompt, and interprets user commands 


MSDOS.SYS, the MS-DOS kernel with many services that is called upon by 
application programs and provides the applications interface (this level is 
invisible to the user) 


10.SYS, containing the BIOS with hardware-specific code, including a col- 
lection of built-in device drivers (some or all may be stored in ROM) 


In IBM PC-DOS, the kernel is called I18MDOS.COM and the BIOS is called 
IBMBIO.COM. 

How has the development of new versions of MS-DOS affected the three 
DOS modules or interfaces? It is interesting to compare two significant revisions 
of MS-DOS in order to see what has grown and by how much (see Table 1-1). 


Table 1-1. Comparison of Two MS-DOS Revisions 


Module DOS 2.0 DOS 3.3 


Size of System Files 


COMMAND.COM 17664 25307 
IBMDOS.COM 4608 22100 
IBMBIO.COM 17152 30159 
Total 39424 77566 


Number of External Commands 


23 35 
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PC-DOS 2.0 was the first “modern” version of MS-DOS, with such features 
as a hierarchical tree-structured system of directories and subdirectories, hard 
disk support, and installable device drivers. Its generic equivalent, MS-DOS 2.11, 
has been the operating system normally distributed with PC compatibles. 
MS-DOS 3.0 and the minor revisions that followed added support for new media 
types (the 1.2MB AT disk, and then 312” 720K and 1.44MB disks) and for net- 
working. It also added several useful new utility commands. 

The table shows that the size of the user interface code COMMAND.COM has 
grown by roughly 50 percent, that of the kernel I1BMDOS.com has exploded by 
about five times, and that of the BIOS has nearly doubled. The number of exter- 
nal commands has also grown by about 50 percent. 

It is hard to draw precise conclusions from this byte length comparison 
because, for example, a significant improvement between versions at the user 
interface level might be reflected mainly by addition of certain system services 
in the kernel or the development of special-purpose external programs rather 
than by an increase in the size of COMMAND. COMitself. Nevertheless, the table does 
reflect what has been the general experience of MS-DOS users: although the 
operating system has grown considerably in size in moving from the 2.X level to 
the 3.X level, most new features have been in the areas of internal routines (sys- 
tem services in the kernel) and in special device support. There has not been 
much added to user interface, batch processing capabilities, or external utility 
commands. 


DOS Startup and Configuration 


The best way to begin to understand how the modules that make up MS-DOS 
work is to go through the highlights of what happens when the system is booted 
or started up. You will see that by the time you see A> on your screen, MS-DOS 
has already been hard at work. It has installed itself in several parts of memory, 
created many important data structures, configured system resources, and in- 
stalled several device drivers. (See Essay 10, Developing MS-DOS Device Drivers, 
by Walter Dixon, for more detailed information on the MS-DOS boot process.) 

From the user point of view, MS-DOS is a series of layers going down from 
the user interface to the kernel and then the BIOS. The boot process goes in the 
opposite direction, however, from the most hardware-specific operations below 
even the BIOS all the way up to the user prompt level. Figure 1-1 is a schematic of 
the overall process. 

In the IBM PC and most other MS-DOS systems, once the built-in ROM 
hardware-checking routines (the POST or Power On Self Test) finishes running, 
bootstrap code in ROM triggers the loading process. This code “knows” just 
enough about the disk to try to read first drive A:, sector 1, track 0, referred to as 
the boot sector in MS-DOS. If there is no disk in drive A: (which is typical of many 
systems today), it tries to read the same location on the hard disk, drive C:. 
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Fig. 1-1. The DOS startup process. 
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The code that has now been read from the boot sector enables the loading 
process to continue. Assuming they are in the root directory of the boot disk, 
10.SYS and then MSDOS.SYS are loaded. (In some MS-DOS implementations, 
10.SYS loads msD0S.SYS rather than both being loaded by the boot sector code.) 
The 10.SYs file actually contains two modules: the BIOS and SYSINIT. The BIOS 
contains the built-in device drivers that allow standard communications with 
the computer's keyboard, screen, printer, serial ports, and disk drives. 

SYSINIT is responsible for a number of coordinating efforts. First, it deter- 
mines the configuration of available memory and relocates the DOS kernel so that 
it goes down from high memory. Second, it calls code in the now loaded MS-DOS 
kernel mspos.sys that builds important data structures or tables MS-DOS will 
need in order to be able to use devices correctly. Each of the resident device driv- 
ers is initialized, and, in turn, returns information about the device that is put into 
a data structure for each device called a Device Control Block (DCB). 

DCBs make up a linked list (a list where each item contains the starting ad- 
dress of the next item), and the starting address of this list is recorded in a global 
list (Sometimes called the List of Lists). This list eventually will contain further 
information such as the largest allowable sector size for block devices. 

Once the built-in drivers are initialized, SYSINIT will attempt to read the 
CONFIG.SYS file. This file, as you probably know, contains user specifications for 
installable device drivers—drivers that can be added to those already resident in 
MS-DOS. These drivers are normally contained in files with the .sYS extension. 
If, for example, you specify DEVICE=VDISK.SYSin your CONF1G.SYS file, the virtual 
disk (RAM disk) will be set up. SYSINITthen collects information about the availa- 
ble devices. As an installable driver is loaded, information about it is added to the 
linked list of device drivers that also includes the names of built-in drivers. Ta- 
bles for tracking active files and the structure of the current directory are also 
set up at this time. The MS-DOS cache (buffer for file 1/O) is also set up based on 
information obtained during the boot process as modified by any user BUFFERS= 
command found in CONFIG.SYS. 

Finally, SYSINIT loads the command interpreter, or shell, normally com- 
MAND.COM. (If there is a SHELL= statement in CONFIG.SYS, the specified shell is 
loaded instead of COMMAND.COM. The size of the DOS “environment” is also deter- 
mined by the value found in a SHELL= statement in CONFIG.SYS or set to the de- 
fault. The DOS environment consists of a number of standard variables such as 
PATH, which we will look at later, as well as room for user-specified variables such 
as those used in batch files. Finally, any AUTOEXEC.BAT file is executed. Entries in 
this file are commonly used to install memory-resident programs and sometimes 
to start a session with a particular application. 

Once all of this is accomplished, either an application specified in 
AUTOEXEC.BAT has been started and is now running, or COMMAND. COMalone is run- 
ning, showing the familiar DOS prompt. 

The startup process tells us several important things about MS-DOS. First, 
the process moves from the hardware-specific level (ROM code, absolute disk 
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sectors, and so on) through the installation of the standard MS-DOS drivers and 
then to user-installable drivers. We thus move from the necessary and built-in 
components to the optional and flexible add-ons such as user-supplied device 
drivers. Next, MS-DOS, as part of the startup process, “learns” many important 
things about the system, and sets up data structures to hold both this informa- 
tion and information that will be obtained in subsequent operations. Finally, 
these structures are flexible enough that any device that can provide the re- 
quired information via a driver can be “hooked in” to the system. 

Now we will look at the top of the iceberg that has emerged from our 
startup process—the user level—in more detail. 


The User Level 


The user interface or shell is the MS-DOS module that is responsible for ac- 
cepting, interpreting, and acting upon the command lines typed at the keyboard 
by the user. Every operating system has to communicate with the user, and 
much of our time is spent dealing with the user interface. It is thus worthwhile to 
see if we can improve the interface so we can get more work done more easily. 
Remember, programmers are users whenever they type an MS-DOS command 
to change directories or delete a file. 

For each command line, the shell must figure out what command or pro- 
gram is to be run, what files it is to use, and what options have been specified. It 
must then load the program, provide it with the required information, run the 
program, and return ready to execute the next command. 


COMMAND .COM: The Standard MS-DOS Shell 


As we noted earlier, the standard MS-DOS interface is provided by a program 
called COMMAND. COM. This program is called a shell because it (metaphorically) sur- 
rounds the operating system proper (the kernel and BIOS layers) and is the 
means by which users can give commands to be run. Any time we see the user 
prompt (such as A>, COMMAND. COM is running. We will now look at how user com- 
mands are processed. 


Finding Commands and Programs 


Figure 1-2 provides a schematic of how COMMAND. COMresponds to commands. We 
will suppose we have just typed CD. COMMAND. COM first parses (breaks into signifi- 
cant parts) the command line and then attempts to load and run the item speci- 
fied, which can be any one of the following: 
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i an internal MS-DOS command (for example, 01k) 


=- a .COM program 


ve 
ye 


~ an .EXE program 
> a .BAT (batch) file 


“Bad command 


or file name” 


Execute Prepare Prepare Interpret 
internal .COM .EXE .BAT 
command program program file 


.EXE 
extension 
? 


.BAT 
extension 
? 


Found in .COM 
internal : extension 
table? ? 


What is the item “DIR”? 


Command Line: A> 


Fig. 1-2. How COMMAND.COM responds to commands. 


COMMAND. COMlooks for the name of the item within a table within its code to 
see if it is an internal command. The routines for executing internal commands 
are included in COMMAND. CoMitself—in memory so they are executed quickly just 
by jumping to the appropriate routine. In the case of our example command 
line, since CD is an internal MS-DOS command, it is found in the table. Since we 
didn’t type any filenames or options on the command line, the 01R command can 
be run right away. Many MS-DOS command lines are more complicated, how- 
ever. If the item is not found in the table, it is assumed to be something external 
to COMMAND.COM—an external command, an application program, or a batch file. 
In this case, COMMAND.COM searches the disk drives for .COM programs, then .EXE 
programs, and finally .BAT files. The search begins in the current drive and di- 
rectory unless the program's path (directory location) is specified on the com- 
mand line. Additional drives and directories are searched if they have been 
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specified as part of the search path. The ability to specify a search path is an 
important feature because it would be very inefficient for MS-DOS to have to 
search through dozens of directories on several drives in search of a particular 
program. By using the SET PATHcommand to give a sequence of drives and direc- 
tories to be searched, the user can specify that the most frequently used directo- 
ries be searched first, making the process much more efficient. Most MS-DOS 
users therefore specify their PATH in the AUTOEXEC.BAT file. 

If the item is found in one of the directories on the search path, com- 
MAND. COMsets up the environment needed to load and run the program (more on 
this later). If the program is not found, the user sees the familiar message Bad 
command or file name. 


Organizing Resources 


The PATH variable gives MS-DOS more flexibility by telling it how the user has 
arranged resources (programs). It solves only part of the problem, however, be- 
cause “resources” also include the data (source code, documents, spreadsheets, 
databases, or whatever) the user wants to work with. Indeed, as users, we are 
really saying to ourselves, “now I want to revise this letter’ not, “now I'll run 
WordPerfect.’ The MS-DOS path, however, is searched only for executable pro- 
gram or batch files, not the data files to be used with our applications. Later 
versions of MS-DOS provide the APPEND command in an attempt to help track 
data files, but MS-DOS has not yet developed a coherent way of looking at re- 
sources. There is no linkage, for example, between a document and the word 
processor that was used to create it. 

Many software designers feel that users are more comfortable when ab- 
stractions such as files and directories are represented by physical objects 
(icons) that can be moved around. Examples of this approach to accessing re- 
sources, graphical interfaces such as those used by the Macintosh or provided 
by Microsoft Windows, have emerged as an alternative to the traditional com- 
mand-line interface. Linking of needed files (but not the use of icons) is also of- 
fered to programmers in an integrated programming environment such as the 
Borland Turbo or Microsoft Quick languages, where the files needed to edit, 
compile, and link a program are brought together automatically. Such links 
could be implemented in a revision of the standard command-line interface, 
however, and future add-on utilities might offer them. 


Parsing, Expansion, and Redirection 


Besides figuring out what command or other program is to be executed, COM- 
MAND. COMalso parses the remainder of the command line and uses the specifica- 
tions found there to find matching filenames and to specify a program's input 
and output. For example, consider this command line: 
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DIR C:\TABLE? ; SORT > LIST 


The internal DIR command is given the file specification ¢:\TABLE? and run. 
Because a wildcard character ? is used in the file specification (pathname), COM- 
MAND.COM searches the specified directory and passes to the DIR command all 
filenames that consist of TABLE plus any one other letter. In other words, the 
compact pathname with wildcards is “expanded” so that it represents all match- 
ing file or path names. 

Besides expanding wildcards, COMMAND. COMalso looks for symbols that tell it 
to redirect input and output from their normal channels. The | or pipe symbol is 
conceptually a pipeline (connection) between two operations (the internal DIR 
command and the external SorT command in our example) so that the output of 
the first operation becomes the input to the second. (Redirection and piping 
were implemented starting with MS-DOS 2.0.) In our example, first COMMAND. COM 
redirects the output of 01R from the default standard output (the screen) to a 
temporary pipe file. DIR then generates its output, which is put in the pipe file. 
sort then runs with its input redirected to take data from the pipe file. The > 
(greater than) symbol following SORT causes COMMAND.COM to redirect the output 
of this command to the file LIst. (The distinction here is that piping connects a 
program with another program, while redirection with the > and < operators 
directs the output or input respectively to a file.) 

Finally, COMMAND. COMalso looks on the command line for option switches, and 
makes them available to the program to be run. For example, the command DIR /w 
means “print a directory listing in wide (multicolumn) format. This facility is not 
limited to MS-DOS commands, however. When any program is run, MS-DOS con- 
structs a block of data called the Program Segment Prefix (PSP) and puts the re- 
mainder of the command line that invoked it (that is, everything but the program 
name itself) into the PSP, so any program can access its command line and check 
for option specifications. PSP is called a prefix because it consists of the first 256 
bytes of the 64K segment that either contains or begins the program code. Figure 
1-3 summarizes the steps that COMMAND. COMtakes in parsing the command line and 
preparing to load the specified program. 

These features benefit programmers and power users in several ways. 
Most programming languages support redirection and piping, so it is easy to 
write filter programs that perform useful chores such as stripping out the high 
bits in WordStar files. Several filters can be connected together with pipes, 
which allows the programs to be used in whatever combination or order makes 
sense. The ability of MS-DOS to pass command-line parameters or switches to a 
program enables the desired behavior of each tool to be specified when it is used 
in a command or batch file. | 

When combined with the batch file facility, filename expansion, redirec- 
tion, piping, and command-line options allow quite a lot of work to be done auto- 
matically —compiling, linking, and running a program, or processing text files in 
converting between formats. 
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Fig. 1-3. Command-line parsing. 


There are some shortcomings to these command-line features, however. 
One of the most annoying is that most commands will not accept multiple 
filenames. For example, you can’t say, del *.bak *.old temp?. Nor can you specify 
several commands on the same command line, except when joining them with a 
pipe. Additionally, the support for wildcards is not uniform throughout the 
MS-DOS command set. For example, you can’t say type report? to list report1 
through report9. In general, the revisers of MS-DOS have paid much more atten- 
tion to adding new commands than they have to increasing the utility and con- 
sistency of the existing ones. We will look at some possible ways to improve this 
situation later. 


Program Execution 


Once COMMAND.COM finishes parsing the command line, the specified program 
must be loaded and run (see Figure 1-4). COMMAND.COM actually has two parts: a 
permanent part and a temporary part. The permanent or resident part contains 
code that monitors for user interrupts (breaks), critical errors, and for a signal 
indicating that the current program has terminated. It also contains code that is 
used to load the temporary or transient part of COMMAND.COM back into memory. 
The transient part contains all of the rest of COMMAND.coM—the command-line 
parser, batch file facility, internal commands, and so on. 
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Fig. 1-4. How COMMAND.COMruns a program. 


Thus, when a program is run, it is loaded into upper memory where it 
frequently overwrites part of COMMAND.COMs transient portion. When the pro- 
gram is terminated, the resident portion does a checksum in order to find out if 
the transient portion is intact. If it is not, a fresh copy is loaded from disk. (The 
variable COMSPEC can be used to tell COMMAND. COM where to look for it.) In floppy- 
based systems, this sometimes requires disk swapping after running an applica- 
tion. 

The reason for having only a minimal part of the shell in permanent resi- 
dence goes back to the fact that, in its earliest incarnation, MS-DOS had to run 
on machines that had only 64K of memory. If all of COMMAND.COM were kept in 
memory, the amount of memory available to application programs would be cor- 
respondingly reduced. Since the size of the user interface continues to grow and 
applications tend to want all available memory, this feature is probably still use- 
ful. 
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Running Multiple Shells 


Note that COMMAND. COM itself, since it is actually “just a program,’ can be run like 
any other program from an existing copy of COMMAND.COoM. Thus at the DOS 
prompt, you can type command /c dir and get a directory. The /c is a switch that 
tells the new COMMAND. COMto execute the rest of the line as a command. The real 
use of this, however, is to have a batch file run another batch file. (m DOS 3.3, 
there is a CALL statement that provides a more straightforward way to do this.) 
You can also have an applications program run a batch file by using a system call 
(the EXEC function), to invoke a new COMMAND.COM with the appropriate command 
line placed in memory. 


Batch Processing 


Another powerful feature of MS-DOS is the ability to put a series of command 
lines in a batch file that can be executed by naming it, in the same way an 
MS-DOS command or other program is run. Indeed, a batch file is a program 
consisting of MS-DOS command lines and some rudimentary branching and 
control structures. Batch files are typically used for such tasks as configuring 
the system at startup, installing new software, and assembling or compiling pro- 
grams. The power user columns of popular PC magazines are filled with batch 
files that perform a number of other chores such as setting a serial port or 
printer. Because they are ordinary text files, batch files can be created with 
whatever editor is handy. 

Much of the power of batch files comes from the fact that they can be given 
general placeholders that can be filled in from the command line when the 
batch file is called. For example, if a batch file called BACKIT.BAT contains the line 
COPY %1 %1.BAK, typing BACKIT LETTER results in the command COPY LETTER LET- 
TER.BAK being executed. 

Unfortunately, the MS-DOS batch facility, despite the creative uses to which 
it has been put, is very limited as a programming language. There is an IF but no 
ELSE, for example. There is a FOR statement, but it accepts only lists and is not 
able to use a counter. Long batch files (such as those used to install software) are 
hard to read and maintain because of the lack of good control structures and the 
inability to use subroutines. In addition, the MS-DOS batch-processing language 
has no facility for performing arithmetic, doing anything other than a literal 
comparison to a string, or even for getting input (other than pausing for a key- 
press) from the user. 

There are several approaches that can be taken to improve MS-DOS batch 
processing. One is to write short utilities that can extend the versatility of the 
batch facility. (See Essay 3, Adding UNIX Power with PCnix, by Edward Nather, 
which describes the use of batch files to implement UNIX-style utilities in 
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MS-DOS. He also describes batch file helpers—short programs that can, for ex- 
ample, check user input in a batch file.) 

Another place to look for more power and ease in batch programming is 
among the many menu-generation programs, some of which are public domain 
or shareware. These programs allow you to set up a nested series of menus to 
guide beginning users, and, in some cases, include batch facilities as well. 

A more comprehensive solution is a product called EBL (Extended Batch 
Language) that provides the many features missing in the MS-DOS batch lan- 
guage, yet is compatible with regular DOS batch files. This is a shareware prod- 
uct available on many bulletin boards. (See Essay 4, Adding Power to MS-DOS 
Programming, by Doug Adams, for a detailed overview of EBL with examples.) 

Finally, there are a number of products that provide implementations of 
UNIX shells for MS-DOS, offering what is, in effect, a general-purpose macro 
programming language. (The Korn shell, ksh, is the most comprehensive one.) 
UNIX shells offer programmers more (and more flexible) variables, better con- 
trol structures, and many more conditions that can be tested. Such shells are 
definitely more complex than COMMAND.COM, but this will not dismay people who 
are already programmers or power users of MS-DOS. The UNIX shells for 
MS-DOS vary in quality. The best I have found is in a product called the MKS 
Toolkit. It provides a very full implementation of the new UNIX Korn shell with 
many UNIX utilities besides. This product is compatible with the rest of the 
MS-DOS environment, including memory-resident programs. It can be run ei- 
ther instead of COMMAND.COMor from it. 


The MS-DOS File System 


Readers of this book are likely to be quite familiar with the use of pathnames, 
directories, and subdirectories to navigate among files under MS-DOS. Of 
course, it is not easy for even a power user to type a pathname like 
c:\c5S\bin\graphics\ega without errors. The significant milestone in the 
MS-DOS file system was the implementation of a tree-structured (hierarchical) 
file structure starting with MS-DOS 2.0. Such a system of directories and sub- 
directories was, of course, made necessary by the advent of hard disks with 
space for hundreds of files. The syntax used is very similar to that of UNIX, ex- 
cept that MS-DOS uses \ to separate parts of a file path, while UNIX uses /. On 
the other hand, MS-DOS uses / for command options, while UNIX uses -. This is 
a continuing frustration to people who use both operating systems daily. (See 
Essay 3, Adding UNIX Power with PCnix, by Edward Nather, for a discussion of 
ways to modify MS-DOS to accept the UNIX conventions.) 

The difficulty many people have in visualizing their place in the file tree has 
led to a number of developments. Numerous commercial DOS shells (which are 
not really shells, since they don’t replace COMMAND.COM) offer users a graphic de- 
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piction of their file structure and easy selection of files for inspection, copying, 
or removal. More radically, graphic environments that follow the Macintosh phi- 
losophy (such as GEM and MS Windows) replace directories and subdirectories 
with folders. These are designed to be more intuitive, especially for beginning 
users, but some graphic interfaces (notably that of the Macintosh) do not allow 
one to use command lines where appropriate. A command line using wildcards 
enables us to act globally (on a whole set of files or a directory) with a single 
command. 

Another shortcoming that is keenly felt by most MS-DOS users is the limita- 
tion of filenames to eight characters plus a three-character extension. One won- 
ders how many person-hours have been lost trying to come up with a way to 
name a document so that you can find it again without having to examine other 
similar files. One solution is to use several layers of subdirectories to specify the 
meaning of a name by its position in the hierarchy. In other words, since you 
can’t use report.income.1987. fall, you can use \reports\income\1987\ fal L. 
Although there are times when such an organization makes sense conceptually 
(perhaps if you have many similar files), it usually substitutes the problem of 
directory navigation mentioned earlier for the problem of incomprehensible 
filenames. Disappointingly, there appears to be no provision in planned new re- 
leases of MS-DOS or OS/2 to allow longer filenames. 

As usual, the market has responded to users’ needs, however—in this case, 
by providing MS-DOS shell or file manager programs (often memory-resident) 
that allow you to associate a longer name or phrase (or keywords) with a 
filename. When your application asks you for a filename, you can pop up the 
utility and use it to find the right name and then invoke the application. 

Going beyond these relatively superficial problems, the MS-DOS file system 
also suffers from a structural problem. Conceptually, one should be able to get 
from any part of the file tree to another, simply by searching recursively. In this 
case, recursive searching means searching the first directory, then searching 
any subdirectories in that directory, searching each of its subdirectories, and so 
on. Indeed, MS-DOS provides system functions that allow programs to navigate 
through the directory hierarchy, but the user commands generally aren’t recur- 
sive. That is, they can’t operate on the current directory and all its subdirecto- 
ries and all their subdirectories. You can’t, for example, copy or delete a 
directory and all of its subdirectories in the way you can in UNIX. (MS-DOS 3.2 
provides a new command called xcopy that is recursive and copies subdirecto- 
ries, however.) 

While it can be argued that such recursion increases the chances of acci- 
dents, it is needed to take full advantage of the file system structure. MS-DOS has 
most of the pieces of the needed facility. For example, starting with DOS 2.0, 
MS-DOS provides a command called tree that displays the directory tree start- 
ing at a specified point. Unfortunately, there is no command that will search 
through this tree and show you the path to a specified file. Nor is there a com- 
mand in standard MS-DOS that allows you to find matching files in the tree and 
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apply an MS-DOS command to them (for example, to find the file REPORT8 some- 
where in the depths of your ACCOUNTS directory and TYPE it to the screen, or to 
DELETE all files with the extension .BAK regardless of their position in the hier- 
archy). In UNIX, this function is performed by the powerful find command, 
which is not to be confused with the MS-DOS FIND command. The latter doesn’t 
find files, but rather finds words in a file. 

Again, enterprising programmers have come to the user's rescue by provid- 
ing a utility that will find matching files anywhere in the file tree, and optionally 
apply an MS-DOS command to them. (See Essay 2, Searching the File Tree with 
whereis, by Frank Whaley, for a very complete implementation of this utility.) 


Strategies for Improving the User Interface 


A “better” interface means two things that are often hard to reconcile: more 
powerful and easier to use. Figure 1-5 shows stylized learning curves for three 
environments: “classic” MS-DOS, the Macintosh-style interface, and UNIX. Each 
plots power along the vertical axis and ease of learning and use along the hori- 
zontal. (These are not meant to be exact quantifications.) 

Classic MS-DOS has a pretty steep learning curve that eventually levels off 
as the user learns features. Unfortunately, the power also levels off quickly due 
to the systemic shortcomings of elements such as the batch-processing and file 
systems and the lack of commands for many functions. 

The Macintosh-style interface offers a more shallow learning curve (it is eas- 
ier to learn) and a higher initial level of power, but the power does not grow signifi- 
cantly over time. It is a bit like the hare and the tortoise: on the average, as a Mac 
user, you will be able to do much more with the operating system in the first 
couple of months than will the MS-DOS (or UNIX) user, but the lack of global com- 
mands and batch processing means that you will not be able to do much more in 
the operating system after six months than you were able to do after one. 

Finally, UNIX offers a learning curve that tends to remain fairly steep, but 
with power that continues to increase. The MS-DOS power user who obtains a 
UNIX-style shell and utilities may be able to accomplish many things the other 
two kinds of users cannot, though any shell scripts created cannot be run on 
another system without also providing a copy of the shell (and probably other 
programs). 

It should be clear that there is a place for both the easy-to-learn graphical 
interface and the power user's command-line interface. Fortunately, both are 
available today. With the use of a product such as Microsoft Windows, a user can 
have access to both worlds, with many other benefits besides. (See Essay 9, In- 
side Microsoft Windows, by Michael Geary.) In addition, integrated program- 
ming environments usually offer a graphic-style windowed interface, access to 
MS-DOS from within the program, and batch-mode compile and link options. 
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Fig. 1-5. Learning ease of use vs. power. 


Programmers and power users may have a bewildering variety of choices these 
days, but with thought and planning they can have both power and ease of use. 


The Applications Level 


At the applications level, we move from what the user needs to what a program- 
mer must do. The programmer's interface to MS-DOS is the applications services 
level—the system kernel, which is loaded from the MspoS. SYS file (IBMDOS. COMin 
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PC-DOS). The kernel contains the data structures and service routines that ap- 
plications programs must access correctly in order to function in the MS-DOS 
environment. 


DOS Kernel Features 


The MS-DOS kernel serves an applications program in two general ways. First, it 
manages information the program needs in order to interact with its environ- 
ment, such as information about the current directory, the files assigned for use 
by the program, and the list of available devices and how they organize data. 
Second, the kernel provides service routines (often called MS-DOS functions or 
interrupts) that handle such things as memory management, file management, 
and I/O for built-in character devices such as the screen, keyboard, parallel port, 
and serial port. 


Program Structure and Memory Use 


To load a program (either a .cCOMor an .EXE), COMMAND. COM calls the kernel’s EXEC 
function INT 48H, which constructs the PSP. (See Essay 6, Undocumented MS-DOS 
Functions, by Ray Michels, which begins with a detailed discussion of the PSP) 

The PSP provides a program with information about its current environ- 
ment, including the values of current DOS variables such as PATH. It also contains 
the remainder of the command line used to call the program, so the program can 
search for and act on option switches and find the names of user-specified files. 

The PSP also contains the addresses of key services the program will need, 
such as the MS-DOS termination handler INT 22H, which provides for the orderly 
termination of a program, and the MS-DOS function dispatcher INT 21H, through 
which requests for disk operations and various I/O services are sent. The PSP 
also provides information that can be used to determine if the program has allo- 
cated enough memory for its needs or perhaps can release some memory. 

The PSP thus provides a private copy of the environment for each program. 
Although only one program can be active at a time, there can be several PSPs 
and associated programs in memory. The PSP for each program serves to iden- 
tify it as a process. This allows the maintenance of multiple memory-resident 
programs. Beyond that, the PSP structure is useful for developing task-switch- 
ing and the provision of variable amounts of processor time for different pro- 
cesses—in other words, a form of multitasking, since each process can be 
maintained with its own PSP. While Microsoft has chosen not to exploit this line 
of development (opting for the much more sophisticated approach in OS/2), 
other vendors have created multitasking versions of DOS or task-switching that 
run under DOS. 
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- COM Program Structure 


As all users learn, there are two types of executable programs that run under 
MS-DOS. The simplest type is the .coMprogram, identified by this file extension. 
A .COM program is an exact image (copy) of binary program code. It is always 
loaded just after the PSP, and it cannot be relocated. A . COMprogram is limited to 
one segment (64K), minus the space for the PSP (256 bytes) and the minimum 
stack (2 bytes). The compensation for this inflexibility is that .cOMprograms are 
compact and load fast, since multiple segments do not have to be accessed. 
Most .COMprograms found these days are usually either old programs (per- 
haps originally ported from CP/M) or small utility programs. The first genera- 
tion of languages on PCs often produced only .coM programs, but most 
compilers can now use large-memory models and produce .E€X€ files. 


- EXE Program Structure 


Larger programs and those that need to be able to allocate and release memory 
as needed are constructed as .EXE programs (using that file extension). The key 
features of an .EXE program, as compared to a .COMprogram, are that it can use 
as many segments of memory as are available, and it can be relocated after load- 
ing. Separate segments can be devoted to program code, data, and the stack. 
Figure 1-6 compares the structures of .cOMand .EXE programs. 

Unlike the case with .cOM programs, which are always loaded as a block, 
MS-DOS must know a lot of information about an . EXE program to be able to load 
it into memory and allocate whatever extra memory is needed. Each .EXE pro- 
gram has a header that includes information such as the location and size of the 
program's code, data, and stack segments. Other header fields tell MS-DOS how 
much more memory the program must have in order to run, and how much 
more the program would like to have if available. An .EXE program can also call 
functions that release memory that is no longer needed. Thus, .ExEprograms, at 
the expense of additional overhead, are much more flexible than are .coM pro- 
grams. 

In the early days of MS-DOS, flexible memory allocation and the ability to 
deallocate unneeded memory were not very important. Normally there would 
be only one program in memory at a time. The advent of memory-resident pro- 
grams changed all of this. An “ill-behaved” program that grabs all available mem- 
ory freezes out memory-resident programs that expect to be able to allocate 
some memory as needed. Today, most programs that are intended to be used in a 
typical MS-DOS environment should be able to release and reclaim memory as 
needed. In addition, .€xE programs that follow certain rules can run under 
MS-DOS, OS/2 (MS-DOS compatible) mode, or OS/2 protected mode. 
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Fig. 1-6. Structure of .COMand .EXE programs. 


Memory-Resident Programs 


The story of the development of memory-resident programs (usually called TSR 
for Terminate and Stay Resident programs) is a fascinating one. (See Essay 7, Safe 
Memory-Resident Programming (TSR), by Steven Baker, for both history and a 
very detailed discussion of the workings of TSRs and potential pitfalls.) A feature 
apparently intended by Microsoft only for reconfiguring access to devices (such 
as the MODE command) or spooling printer output (the PRINT command) was un- 
earthed by eager developers and exploited to bring us SideKick and dozens of 
other utilities that are available at the touch of a key. Indeed, one of the biggest 
problems for serious users today is deciding how many of these attractive pro- 
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grams can be fit into the 640K of total available memory while still leaving room 
for an applications program. 

As noted earlier, there can be multiple programs, each with its own PSP, in 
memory at the same time. Normally an MS-DOS program is removed from mem- 
ory (or more precisely, its memory is released) after it terminates. When a TSR 
program first runs, it calls a function (usually INT 21H, Function 31H that tells 
MS-DOS to maintain the program in memory even after it has exited. By using 
the interrupt mechanism, a TSR can set things up so it is triggered when an 
event such as a specific keypress is encountered. Problems occur when two 
TSRs are set to respond to the same keypress, or a TSR does not pass on the 
keystrokes it examines so other TSRs can check them. 

In essence, the TSR facility, because it allows multiple programs (processes) 
to exist simultaneously, provides the capability of task-switching. Since several 
programs are in memory and each can be selected by a particular keypress, the 
user can switch “instantly” between them. Memory-residency potentially sup- 
ports an object-oriented, event-driven approach where a program could be con- 
structed of modules that can respond to “messages” sent to them by various 
events. Programmers can explore the possibility of implementing an application 
as a group of memory-resident modules. The drawbacks are considerable how- 
ever. Many important functions relating to TSRs have only been documented re- 
cently, some are still undocumented. MS Windows and ultimately OS/2 are much 
better environments for developing such event-driven programs, but there is 
still room for exploiting memory-resident programming in the standard 
MS-DOS environment. 


Accessing System Services through Interrupts 


The basic mechanism by which programs request the services of the MS-DOS 
kernel is the software interrupt. There are basically two kinds of interrupts in the 
PC environment: hardware interrupts and software interrupts. Hardware inter- 
rupts originate from the hardware controlling devices, and programs must re- 
spond appropriately to them. Remember, there is nothing traumatic or unusual 
about hardware interrupts in the MS-DOS world. Many are nothing more than a 
device saying that it has completed the requested I/O operation. 

Software interrupts are used by programs to obtain such services as file 
management (creating, writing, and reading files, creating directories, and so 
on), memory management (allocating or releasing memory), reading the key- 
board, displaying text or graphics, or running a program from the current pro- 
gram. 

Interrupts are referred to as INT XXH where XXis a hexadecimal number. INT 
is also the name of the assembly language instruction used to call an interrupt. 

Software interrupts can access the BIOS for low-level operations, and this is 
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sometimes done for speed reasons. For example, INT 10H is a general-purpose 
interrupt used to access the BIOS video services. In general, however, the most 
compatible way to request DOS services is through the software interrupts that 
call code within the MS-DOS kernel. An interrupt with special significance here 
is INT 21H. This interrupt is a general dispatcher used for calling most of the 
MS-DOS kernel’s system services. Aproximately 100 different functions are avail- 
able through INT 21H, called by putting the hexadecimal number of the specified 
service into the AH register, loading other registers with codes that specify the 
desired processing, and then using the INT 21H instruction. 


The INT Instruction 


Software interrupts are activated by executing the INT assembly language in- 
struction. The form of the instruction is INT n, where nis the hexadecimal inter- 
rupt number. Before the INT statement is executed, CPU registers must be 
loaded with appropriate values as specified in the description of the interrupt. 
When the interrupt returns control to the program, return values, as appropri- 
ate, are provided in the registers. 

The INTinstruction first directs the CPU to save the current contents of the 
code segment (CS) and instruction pointer (IP) registers onto the stack. This must 
be done so that the program that was interrupted can be started up where it left 
off. New values are then loaded into these registers using the values found in the 
Interrupt Vector Table in the first 1024 bytes of memory. The interrupt number 
serves as an index into the table. The CPU then executes the code found at the 
locations now specified by the CS and IP registers, and, when done, restores the 
original CS and IP values from the stack. Execution of the interrupted program 
now resumes. 

Because values in the Interrupt Vector Table can be replaced by the pro- 
grammer with other values, software designers can substitute their own code 
for handling a particular interrupt by putting appropriate values in the table for 
that interrupt number. This is how, for example, a TSR can intercept a keyboard 
interrupt with code that checks for certain keystrokes. 


Using MS-DOS Data Structures 


The use of the many system functions (or interrupts) involves not only an under- 
standing of how a particular interrupt works, but frequently how it uses internal 
MS-DOS data structures. For example, a number of MS-DOS functions have to do 
with file management: creating, writing, reading, closing, and removing files. 
Internally, MS-DOS uses a System File Table (SFT) and individual data blocks 
called File Control Blocks (FCBs) to manage files. The SFT keeps track of the sta- 
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tus of all files that are currently open. Each file has its own FCB, which contains 
the file’s name, status, history (when it was last accessed), as well as pointers to 
the location within the file that was last accessed. 

Constructing FCBs used to be a tedious process because all of this informa- 
tion had to be obtained by the program and inserted one field at a time. But 
MS-DOS (starting with version 2.0) has provided an alternate and preferable way 
for applications to handle files, the file handle. The programmer obtains a file 
handle by passing the address of a string containing the pathname of the file to 
the file creation or file-opening function. The handle that is returned is a 16-bit 
value that identifies that file. All further references to the file use only the han- 
dle, and MS-DOS keeps track of the file’s FCB without further ado. The use of file 
handles makes it easy to find a file anywhere in the file system hierarchy, redi- 
rect input and output, and control the use of files and records in a network envi- 
ronment. 

The file handle example is typical of a problem with learning how to pro- 
gram with MS-DOS. In the interest of compatibility with earlier versions, many 
MS-DOS facilities do not replace the functions they are intended to supplant. It is 
up to the programmer to learn what the preferred techniques are. (See Essay 10, 
Developing MS-DOS Device Drivers, by Walter Dixon, and Essay 6, Undocu- 
mented MS-DOS Functions, by Ray Michels, for discussions of the use of the SFT, 
FCB, and file handles.) 


Problems in Interrupt Handling 


While the interrupt mechanism is conceptually simple, in practice, many 
problems can occur in managing interrupts. As the name implies, an interrupt 
“interrupts” whatever program was running when it was triggered, so the han- 
dler for the interrupt must properly save and restore the interrupted program's 
register values. The programmer must also be concerned with preventing inter- 
rupts from interrupting themselves. 

The interrupt mechanism worked well in the environment for which it was 
designed (only one program running at a time). The use of interrupt-driven TSR 
programs complicates the issue—the problem is that there is no way to protect 
the system from the misbehavior of one process or from an improperly handled 
interrupt. In most multitasking operating systems such as UNIX or OS/2, pro- 
grammers request system services and access memory only through the operat- 
ing system, not by means of interrupts. The operating system is an ever-present 
monitor, not just a program loader. The OS protects each program's memory 
from unauthorized access. This kind of memory management and the use of 
protected mode (on the 80X86) means that an errant program can commit sui- 
cide, but cannot murder another program. (See Essay 10, Developing MS-DOS 
Device Drivers, by Walter Dixon, for a detailed discussion of the interrupt mech- 
anism. See Essay 5, Advanced MASM Techniques, by Michael Goldman, for tech- 
niques and tips for proper handling of interrupts.) 
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New Programming Tools and Techniques 


Applications programming requires good tools as well as knowledge and tech- 
niques. The last few years have seen the emergence of powerful and versatile 
tools for programmers, and of integrated programming environments that make 
it easier to use them. The new programming tools also make it easier for begin- 
ning programmers, traditionally introduced to BASIC, to move directly to using C 
or other languages that are better designed for professional programming. 


Integrated Programming Environments 


Borland International started a small revolution with the introduction of its fast, 
cheap, and easy to use Turbo Pascal product. Instead of a tedious write-compile- 
link-run-debug-revise cycle, programmers could now write code in an editor, 
have it compiled, linked, and run automatically, and immediately invoke the editor 
to fix any errors that emerge. The control of all aspects of the programming pro- 
cess from the same interface provided an integrated programming environment. 

Since then, Borland and Microsoft have brought out products that add 
power while retaining the easy-to-use pull-down menus and dialog windows. 
Microsoft C 5.0 is particularly noteworthy in that it offers an integrated environ- 
ment (QuickC) that is fully compatible with the full-fledged command-line 
driven compiler, linker, and librarian, and provides a subset of its CodeView de- 
bugger commands from within the integrated environment. 

The significance of integrated environments is that they help program- 
mers concentrate on the design and coding of the program rather than the me- 
chanics of keeping track of include files, compiler options, “make” files, and 
other housekeeping details. 

A further step toward programming ease has recently been taken by 
Microsoft, starting with its QuickBASIC 4.0 product. By using a “threaded” mech- 
anism for linking compiled code sections, this integrated environment makes it 
possible in many cases to recompile and relink just the parts of the program 
affected by the most recent edit. 

Another trend that is seen especially in the Microsoft and Borland prod- 
ucts is the provision of a uniform interface that allows programs created using 
one language to call routines created using another language. This is mainly a 
matter of having the compiled code from each language pass parameters on the 
stack using the same sequence. This “multilanguage programming” provides 
flexibility in using existing resources and allows the programmer to choose the 
language best suited for a given task. 


C Function Libraries 


The general acceptance of C as the premier higher-level language for MS-DOS 
programming has resulted in the development of numerous commercial and 
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public-domain libraries of C functions for nearly everything one might want to 
do with an MS-DOS system and its hardware. (Two good examples on a small 
scale are the serial communications routines in Essay 13, Programming the Se- 
rial Port with C, by Naba Barkakati, and the EGA graphics routines in Essay 12, 
Programming the Enhanced Graphics Adapter (EGA) by Andrew Dumke. Essay 
4, Adding Power to MS-DOS Programming, by Doug Adams, describes the fea- 
tures and gives examples of the use of two commercial C libraries: Vitamin C, a 
screen generator, and C-INDEX, an indexed file-retrieval system. 


The Hardware Level 


Finally we come to the lowest (but certainly not least important) level of MS-DOS, 
the interface to hardware. When all is said and done, a program must communi- 
cate effectively with the outside world. From lowest to highest level, there are 
three ways a program can control devices: direct access, BIOS calls, and device 
drivers. 

Direct access involves directly manipulating the registers or memory loca- 
tions associated with devices connected with the system, or directly accessing 
memory buffers associated with the devices. In general, this is usually done for 
speed—in the case of the video display, for example, to provide high-speed draw- 
ing and animation. The drawback of this approach is that it depends on exact 
hardware compatibility, which is not the same as the “functional compatibility” 
advertised particularly by the early PC-compatibile vendors. Most software de- 
velopers avoid this approach, except in some games. 


The BIOS 


In our discussion of interrupts we mentioned the BIOS calls available through 
INT 10H. Since the calls for device services through the BIOS have to be translated 
into specific register or memory changes, this approach is slower than direct 
access. On the other hand, now that very highly compatible BIOS chips for PC 
compatibles are widely available, the BIOS approach guarantees a high degree of 
compatibility. 


Communicating with Devices 


The third approach to communicating with hardware is the device driver. A de- 
vice driver is a program that is installed by MS-DOS in memory where it waits 
for control sequences directed at a particular device. The driver translates these 
commands into the low-level instructions needed to get the device to perform 


29 


Section 1: Extending the MS-DOS User Interface 


the required function. MS-DOS comes with a number of built-in device drivers 
for the devices that are built into every PC, such as the keyboard, disk drives, 
and parallel and serial ports. 


Installable Device Drivers 


The open architecture of the IBM PC and its compatibles rapidly led to the prolif- 
eration of add-on devices. In the area of the video display, IBM offered the EGA 
and the Video Graphics Array (VGA) and other adapters to provide more resolu- 
tion and color. Meanwhile, Hercules established its own display “standard? Modi- 
fying the BIOS or the MS-DOS kernel to keep up with these new devices would 
have led to a logistical nightmare. Instead, MS-DOS 2.0 added the capability for 
users to install their own device drivers. 

As we mentioned in the discussion of the DOS boot process, MS-DOS builds 
a list of device drivers that starts with its own built-in drivers. MS-DOS also pro- 
vides some optional drivers, such as ANSI.SYS (a console driver) and VDISK.SYS (a 
RAMdisk driver). These or drivers written by other programmers can be in- 
stalled (hooked into the MS-DOS driver list), and a DEVICE= statement naming the 
driver in the CONFIG.SYS file then tells MS-DOS to install the driver at system 
startup. (See Essay 11, Writing a SOUND Device Driver, by Walter Dixon, for a 
complete minicourse on designing, using, and testing installable device drivers.) 

The installable device driver is one of MS-DOS's outstanding successes. In 
addition to accommodating new devices such as laser printers or CD drives, de- 
vice drivers can even be used to intercept file accesses and provide password 
protection. (See Essay 8, Data Protection and Encryption, by Asael Dror.) 


The Future of MS-DOS 


30 


Microsoft Windows, with the recent release of version 2.0, represents several 
fundamental extensions of the MS-DOS environment without sacrificing the un- 
derlying MS-DOS kernel. For users, it provides a graphical user interface with 


most of the features popularized by the Macintosh. For programmers, however, 


the real significance of MS Windows is that it provides a new model for thinking 
about and designing programs. This is the model that is often called object-ori- 
ented programming. Instead of an application being written as a collection of 
functions that are called according to the logic of the main program, each Win- 
dows function is designed to handle specified inputs (messages) and send mes- 
sages in return to the central dispatcher. Events such as mouse movements thus 
become input to the function controlling each window. 

In a traditional program, the user is put in the position of an applicant who 
must fill out a series of forms (navigate menus) in order to get to the point of 
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being able to do some work. In an object-oriented, “modeless” program, the user 
picks up the desired tool and the tool responds in a way that seems natural for 
the intended work. While in practice, Windows may not be this seamless, it pro- 
vides a taste of things to come. (See Essay 9, Inside Microsoft Windows, by Mi- 
chael Geary, for more discussion on the Windows interface and programming 
environment.) 


Expanded Memory 


The proliferation of TSRs, the overhead involved with environments such as MS 
Windows, and the sheer amount of data that applications are now called upon to 
handle often leads to a shortage of usable memory. Remember, MS-DOS allows 
only 640K of memory to be addressed directly. The ultimate solution is an oper- 
ating system that takes advantage of the “protected mode” of the 80286 and 
80386 to address many megabytes of memory, such as OS/2 or UNIX. Meanwhile, 
EMS, a workable if not ideal solution, allows access to memory beyond 640K 
under MS-DOS. Portions of the 640K main memory are treated as windows into 
which chunks of memory from a memory expansion board can be mapped as 
needed. While this technique is slower than being able to directly address the 
extra memory (and involves housekeeping), it is much faster than using the hard 
disk for swapping code or data in and out. Increasing numbers of applications 
are being written or revised to take advantage of EMS or its successors, En- 
hanced Extended Memory Specification (EEMS) and EMS 4.0. (See Essay 14, Un- 
derstanding Expanded Memory Systems, by Ray Duncan, for a conceptual and 
practical understanding of expanded memory and how a program can use it.) 


OS/2 


Even granting its shortcomings and limitations, by any standard, MS-DOS has 
been a remarkable success. Microsoft has added significant features to the oper- 
ating system on several occasions, and has been innovative in the areas of oper- 
ating environments (MS Windows) and programming tools (of which Codeview 
and the “Quick” integrated environments are most notable). Perhaps the real 
driving force behind the success of MS-DOS, however, is the community of devel- 
opers who have discovered and exploited features such as memory -resident pro- 
gramming to meet an increasingly demanding market. 

It is traditional in the computer industry to want to be where the action is— 
the latest wave rather than the tried and true. There is no doubt that in the long 
run OS/2 is the successor to MS-DOS, providing multitasking, a new user inter- 
face (Presentation Manager), and a new programming environment. 

On the other hand, there is a huge installed base of PCs and XTs that will 
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never be upgraded to run OS/2. Also, OS/2 is significantly more expensive than 
MS-DOS, especially considering its hefty memory requirements and the cost of 
replacing all applications in order to take full advantage of OS/2, rather than 
merely running in a slightly degraded fashion in a compatibility mode. Further, it 
will take time to rewrite significant applications to take advantage of OS/2, and 
until new applications are conceived that take full advantage of multitasking in 
their design, there will be limited incentive for most ordinary users to learn OS/2 
instead of using a combination such as MS-DOS, Windows, and EMS. Thus it is 
likely that, for at least the next several years, there will be a significant market for 
MS-DOS applications and considerable room for innovation in the MS-DOS world. 
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32 


Angermeyer, J., R. Fahringer, K. Jaeger, and D. Shafer/The Waite Group. 1987. 
Tricks of the MS-DOS Masters. Indianapolis: Howard W. Sams & Company. 
‘ Full of tips that turn users into power users, including ways to enhance 
MS-DOS with add-on products. 


Angermeyer, J., and K. Jaeger/The Waite Group. 1986. MS-DOS Developer's 

Guide. Indianapolis: Howard W. Sams & Company. 

= Contains many strategies and techniques for program development 
under MS-DOS including real-time programming, the 8087 coprocessor, 


and network support. 


Duncan, R. 1986. Advanced MS-DOS. Redmond, Washington: Microsoft Press. 
* A very thorough guide to MS-DOS internal structures and system func- 
tions with numerous examples in assembly language. 


Mortice Kern Systems. 1986. MKS Toolkit. Waterloo, Ontario, Canada. 
‘ Describes the MKS toolkit, a product that provides a very UNIX-like envi- 
ronment under MS-DOS, including the Korn shell. 


Simrin, S./The Waite Group. 1985. MS-DOS Bible. Indianapolis: Howard W. Sams 
& Company. 
- Guide to MS-DOS features for power users and programmers. 


Chapter 1: A Guided Tour 


RN iW BEERS 0 MET TE a TY eer Sra hata A TE a a ee ae ee re ee th er a 


Harry Henderson is a freelance technical writer and editor specializing in oper- 
ating systems and programming languages. He has worked on numerous books for 
The Waite Group and Sams Publications, including their UNIX series, and is technical 
editor for MS-DOS Papers. He also works with his wife, Lisa Yount, on educational 
writing, under the close supervision of three cats. 


Related Essays 


2 Searching the File Tree with whereis 

3 Adding UNIX Power with PCnix 

4 Adding Power to MS-DOS Programming 
9 Inside Microsoft Windows 


33 


Keywords 
tree-structured directories 
recursive search algorithms 
filename matching _ 
uherat s (utility) 
find (UNIX utility) 


Essay Synopsis: Most MS-DOS users 
are familiar with the concept of tree-struc- 
tured directories. Unfortunately, MS-DOS 
does not provide user commands for finding 
particular files in the file tree and process- 
ing them. Additionally, many programmers 
are not aware of the techniques needed to 


enable programs to traverse the directory 


tree and search for files that match particu- 


Jar criteria. Because subdirectories are 
~- nested, a recursive algorithm allows pro- 


grams to access the subdirectories within a 


given directory, the subdirectories of these 


subdirectories, and so on. This essay dis- 


cusses the algorithms and proper DOS calls 


to use for a program to access to the 
MS-DOS file system. As an illustration, a 
very powerful utility called whereis, written 
in Microsoft C, is provided and fully ex- 
plained. This utility allows you to search for 
files throughout the directory tree and au- 
tomatically apply MS-DOS commands or 


other programs to matching files. 


= 


Searching the File Tree with 
whereis 
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Frank Whaley 


The more recent releases of MS-DOS (versions 2.0 and above) provide a very 
useful feature that can be a tremendous aid to organizing disk files—Tree-Struc- 
tured Directories (also known as a hierarchical file system). However, users and 
programmers are often confused about how to use this feature properly. While 
we will assume that you possess a working knowledge of MS-DOS directories 
(including the commands for directory creation, deletion, and other mainte- 
nance activities), we will review the basic concepts of MS-DOS directories and 
show why directory searching is a required task of many programs. 

The directory search program whereis searches all of the directories on a 
disk for a given set of filenames provided on the command line. The whereis 
program also contains a number of options which turn it into a useful file utility 
program that can move, delete, copy, or perform other operations on the located 
files. As you study whereis, you will learn how to access and best use the 
MS-DOS file system. In addition, this program contains a number of valuable 
subroutines that may be clipped out and used in other programs. 

whereis is actually very similar to the UNIX command find, but has been 
slightly modified to be more like the FileFind program from Peter Norton's The 
Norton Utilities. These alterations allow for simpler command lines (at least for 
the simpler commands) and give whereis more of a regular MS-DOS flavor. We 
could not use the name find, as this is the name of the standard MS-DOS text 
pattern-matching program. 


Tree-Structured Directories 


Just as a hierarchy of offices, filing cabinets, file drawers, and folders can be 
used to organize paperwork, the tree-structured directories provided by 
MS-DOS allow us to organize our disk files into a hierarchical structure. A prac- 
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tical application of such a system would be organizing your disk files so you 
could have subdirectories for each subcategory of your work (for example, all 
files pertaining to material purchases in one directory, and all files pertaining to 
equipment purchases in another). This approach has many advantages: 


» Related files are kept in the same area, and their names can be seen to- 
gether in a single directory listing. 


‘» More significant characters become available for creating unique and 
meaningful filenames (compare DPCMJN with DETROIT\PROD\COSTS\ 
MATERIAL\JUNE). 


i Files containing similar information may have the same name, provided 
they are kept in different directories (APRIL\SALES and MAY\SALES). 


“= MS-DOS requires less search time to find a given file if there are fewer 
files in the current directory. 


One shortcoming of this type of directory structure, however, is that files 
may become lost. They may be created in the wrong directory, or you may sim- 
ply forget where a file was put. A tool for automatic directory searching be- 
comes very useful, particularly when you have a hard disk with dozens of 
directories and hundreds of files. It is for this reason that we selected whereisas 
a method for demonstrating some of the principles of directory searching. 


Searching: The Recursive Solution 
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As with most computer programs, there are several methods that we could use 
to search directories. Seemingly straightforward methods involving nested 
loops require a considerable amount of housekeeping code—stacks of directory 
information must be maintained. 

One of the definitions of a directory is “an object which may contain files or 
other directories” Since this definition is self-referential (or recursive), it would 
seem that a recursive algorithm might be used for directory search. In fact, re- 
cursive methods are the most common methods used with tree-oriented data 
structures, because they allow for simplification of the code required to exam- 
ine each branch of the tree. For example, our whereis program revolves around 
a very simple algorithm: 


1. Find all plain files in this directory. 


2. Repeat for all subdirectories in this directory. 


This method of searching is very much different from what is required by 
most commercial programs. For example, finding a help message file typically 
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involves appending the name of the file to each element of a list of directories, 
and testing for the presence of each constructed filename. Some programs can 
get away with assuming that all pertinent files exist in the current directory, and 
that any other condition is cause enough to abort the program. 

The method used by whereis is most aptly suited to cases where all in- 
stances of a certain class of file must be operated on at one time. These files may 
be selected either by name, type, attributes, or some other condition or combi- 
nation of conditions. 


Directory Search Functions 


MS-DOS was not the first, nor is it the only, operating system to provide tree- 
structured directories. While there is a remarkable similarity between the 
appearance of MS-DOS directories and those used by other systems, MS-DOS 
provides one of the simplest methods for finding files and information about 
these files. 

MS-DOS directories are viewed as special files, and can only be accessed via 
two special function calls through INT 21H: Search For First (Function 4EH) and 
Search For Next (Function 4FH). (In truth, the actual disk sectors that contain the 
directory information may be read via the Absolute Disk Read interrupt (num- 
ber 25H), but this method requires much more programming and is usually con- 
sidered appropriate only for programs which help recover data after a major 
disk failure.) Although these function calls are primarily designed for finding 
files, they actually provide more information than similar functions in other op- 
erating systems. 

The First/Next function calls perform wildcard matching (? and *) and de- 
posit information about the matched file into a predefined data area. This data 
area is described by the following C structure: 


typedef struct /* Directory Information */ 


{ 

char r{21); /* data area reserved by MS-DOS */ 

char attr; /* attribute (system,hidden,etc.) */ 

unsigned time, /* time stamp */ 
date; /* date stamp */ 

long size; /* file size in bytes */ 

char name(13]; /* actual file name */ 

} 

DIRINFO; 


MS-DOS uses the concept of a Data Transfer Area (DTA) for passing blocks 
of data which are too large to be contained in registers. The current DTA is used 
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by MS-DOS to return the DIRINFOstructure shown above. The current DTA must 
be set before each First/Next function call. This process is handled by the 
SETDTA() macro. 

The First/Next function call pair allows the controlling loop of a directory 
search routine to be reduced to just a few lines, as shown in the pseudocode 
below: 


if (a first match can be found) 
{ 
process the matched file 
while (subsequent matches are found) 
process the matched file 
} 


Examine the Search() subroutine within the whereis program (listed at the 
end of this chapter) for another example of this technique. 


Using Options for Power and Flexibility 
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Options are what allow simple programs to perform more than one task, 
thereby increasing both their power and utility. While it may sometimes be 
enough to be able to say 


whereis thisfile 
to find all of the various versions of thisfile, adding a few options like 
whereis -r -b-5000 -t+30 thisfile 


uses the same program to find all of the occurrences of thisfile that are read- 
only, less than 5000 bytes long, and more than 30 days old. 
whereis searches all directories on the current drive for files which match 
both the selected options (or defaults) and one of the file specifications (file- 
specs). In the option descriptions given in Table 2-1, the argument nis expected 
to be a decimal integer where + nmeans more than n, nmeans less than n, and n 
means exactly n. For options that have parameters, the parameter may be given 
either as part of the option argument -t+10or as the next argument -o \bin. 
filespecs may be any list of ambiguous filenames. If filespecs is not pro- 
vided, *.* (all files) is assumed. The following are a few ways that we can use 
whereis. 
To find all .h files: 


whereis *.h 


The 
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Table 2-1. Options for whereis 


Sys SSS eS 
Option Function 


advshr — Match files with given attribute bit set (Archive [a], Directory {d], Volume-label 
[v}, System [s], Hidden [h}, and Read-only [r)). Each attribute must be specified 
separately (as -a ~s —r). 


bn Match files n bytes long. 

tn Match files whose date stamps are n days before today. 

o dir Begin searching at the directory dir instead of the root directory. 

e cmd Execute the command cmd for each matched file, substituting the current 


filename for any '$' found in cmd. Multiple e commands may be included, 
and each will be executed in the order encountered. The commands should 
be quoted (as ''dir $") since most commands contain spaces. 


nS] S])93 on 


To show the directory hierarchy: 

whereis -d | sort 

To find all program files that are also marked System, Hidden, and Read-Only: 
whereis ~s -h -r *.com *.exe *.bat 

To delete all .wks files that are more than 30 days old: 

whereis -t+30 -e "del $" *.wks 

To copy all .arc files to a floppy disk: 

whereis *.arc -e "copy $ a:" 

To create an archive of all .txt files marked Archive and then delete the txt files: 


whereis -a *.txt -e "echo CARCHIVE: $) >>archive'' 
-e ''type $ >>archive" -e "del $' 


whereis.c Program 


The whereis program is a fairly self-contained module—except for library sub- 
routines, all of the code is contained in a single file, whereis.c. As is typical in C 
programs, the first section contains some identification and some constant defi- 
nitions. This version of whereis is coded to conform to the standards of the 
Microsoft C compiler, releases 3.0 and 4.0. 
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Includes and Constants 


The source listings shown on the next several pages comprise the entire text of 
the whereis program. You may create your own copy of this source code by en- 
tering all of the blocks of text shown in computer font. 


/* 

* whereis.c -> find files 

*/ 

#define LINT_ARGS /x strict type checking */ 


#include <stdio.h> 
Hinclude <ctype.h> 
#include <dos.h> 

#include <direct.h> 
#Hinclude <signal.h> 


/* constants */ 
#define ARC 0x20 /* attribute bits */ 
#define DIR 0x10 
H#define VOL 0x08 
H#define SYS 0x04 
#define HID 0x02 
#define RDO 0x01 
/* match plain files */ 
H#define PLAIN (SYS | HID) 
/* match subdirectories */ 
fidefine SUBDIR (DIR | SYS ! HID ! RDO) 


These constants refer to the file attribute flags contained within a direc- 
tory entry (the attr element of the DIRINFOstructure). Note that these values are 


used to specify which types of files to match. 


Directory Information Structure 


As stated earlier, the First/Next function calls fill in a data area providing some 
information about the currently matched file. This information can be used to 
help select the appropriate file: 


/x data types */ 
typedef struct /* Directory Information */ 
{ 
char r(21); /* reserved data */ 
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char attr; /* attribute found */ 

unsigned time, /* time mark */ 
date; /*x date mark */ 

long size; /x file size */ 

char name[13]; /* file name */ 

} 

DIRINFO; 


Macros and Functions for MS-DOS Access 


Let's look next at the interface between our whereis program and MS-DOS. 
Three macros are provided to allow for relatively easy modification to fit the 
library functions provided by your favorite C compiler. The Microsoft C library 
contains many functions to interface to MS-DOS, but whereis requires a connec- 
tion that is not provided in a simple fashion. The First/Next function calls expect 
input parameters in the CX and DX registers, and they return a flag in the AL 
register. There is no MS-DOS interface function in the Microsoft C library that 
passes data in exactly this way, so we have included an interface function which 
serves exactly our purpose. 


/* 

* macros 

*/ 
#define SETDTA(Cd) dos(Ox1A, d) /* set DTA */ 
#define FIRST(f,a) Idos(Ox4E, f, a) /* search for first */ 
#define NEXT() !dos (Ox4F) /* search for next */ 
/* 

* dos() -> connect to MS-DOS 

*/ 


unsigned char dos (ah, dx, cx) 
unsigned char ah; 


char *dx; 
unsigned CX; 
{ 

union REGS ry 


r.h.ah = ah; 

r.x.dx = Cunsigned)dx; 
r.x.CX = Cx; 

intdos (&r, &r); 
return (r.h.al); 

} 
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Note that the First/Next function calls return zero if a matched file is found, 
and nonzero if no match was found. In order to make the function usage seman- 
tically correct (FIRST() returns TRUE if a match is found), we must reverse the 
sense of the functions with the ! operator. 

The fourth macro AddFile() is included only as a shorthand definition of a 
simple function that adds a single file specification to the list of file specifica- 
tions. 


#define AddFile(f) FileList(nFiles++J=f /* add filespec */ 
Next we see the global data used by the program. 


/x global data */ 


char *Exec(32], /* execute commands, from -e */ 
*FileList[32], /x the list of filespecs *x/ 
StartDir(128], /x initial directory *x/ 
*TopDir = '\\": /* start directory, from -o */ 
int AttrMask = 0, /* mask for attribute search */ 
ByteFlag = 0, /* controls size searching */ 
DateFlag = QO, /* controls date searching */ 
DateStamp = -1, /x date stamp to match */ 
nExecs = Q, /*x number of execute commands */ 
nFiles = 0, /x number of filespecs given */ 
Today; /x today's date stamp */ 
long ByteCount = -1; /x file size to match */ 


/* offsets of "first of month" from "first of year" */ 
int months{] ={ 0, 31, 59, 90, 120, 151, 
181, 212, 243, 273, 304, 334 }; 


Both ByteFlag and DateFlag control the sense of comparison (1,0,1 repre- 
sents <,=,)),and DateStamp and ByteCount contain the data to compare against. 
Note that both the Exec and FileList arrays have 32 elements at most. This 
means that there is a maximum of 32 ‘execute’ commands and 32 file specifica- 
tions allowed on the command line. There is no overflow checking in the whereis 
program—we assume that the user will always enter less than 32 of either item. 


Forward Declarations 


In general, C programs are coded in a top-down fashion, with the main routine 
appearing as the first function. This is usually done to show the basic structure 
of the program. Therefore the functions that do not return integers must have 


Chapter 2: Searching the File Tree 


forward declarations. (They must be described before they may be used.) This 
forward declaration informs the compiler that these functions do not return the 
default data type (integer), and prevents the compiler from complaining when it 
later finds the formal definitions of these functions: 


int 
void 


GracefulDeath(void); 
Handle(DIRINFO *), 
ParseCommandLineCint, char **), 
Search(void); 


Note that even though the GracefulDeath() function does return an integer 


value, its name is used as a function parameter (see the call to signal) in the 
next section), and must be declared before use to prevent confusing the com- 


piler. 


The Main Program 


As the leading comment says, the program proper begins with “good old main’: 


/x 


* 


*/ 


good old main 


int main(argce, argv) 


int argc; 

char *argv[]; 

{ 

/* get today's day number */ 
Today = SysDate(); 

/* pick options and filespecs from command Line 
ParseCommandLine(argc, argv); 

/*x save initial directory */ 
getcwd(StartDir, sizeof(StartDir)); 
/* set the interrupt handler */ 
signal (SIGINT, GracefulDeath); 

/* move to starting directory */ 
chdir(TopDir); 

/x any filenames given 7? */ 

if (!nFiles) 


AddFile c''«, x!) : /* anice default */ 
/* search for named files */ 
Search(); 


/* pop back to initial directory */ 


*/ 
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chdir(StartDir); 

/* successful return */ 
return (0); 

} 


Handling Interrupts Gracefully 


Before any directory searching can begin, we want to be certain that we have a 
safe environment. The next function serves as the interrupt handler for whereis. 
Because whereis uses the standard library function chdir() to move through the 
directory tree, aborting the program may cause the program to leave the users 
in some directory other than where they started. This is a typical source of lost 
files—some program leaves the user in a different directory than was intended, 
and files are created there never to be found again. It would be unforgivable to 
allow our file finder program to make a mistake like that, so let us ensure that 
whereis dies a graceful death: 


/* 
* GracefulDeath() -> clean-up upon interrupt 
*/ 
int GracefulDeath() 
{ 
chdir(StartDir); 
exit (1); 
} 


The Directory Search Function 


Now that we have taken care of potential interrupts, we move to the starting di- 
rectory. We use any file specifications that were given on the command line. If 
there were none, *.+ (all files) is used as the default. The Search() subroutine is 
called to perform most of the work: 


/* 
* Search() -> search for files 
*/ 
void Search ) 

{ 

DIRINFO info; 

int i 

first; 
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/* search current directory for all filenames */ 
for (i = 0; i < nFiles; i++) 
{ 
first = 1; 
while (Scan(FileListli], &info, PLAIN |} AttrMask, first)) 


{ 
first = 0; 
if Cinfo.name(0) != '.') /* skip "." and "1." x/ 
Handle (&info); 
} 
} 
/* search all subdirectories */ 
first = 1; 
while (Scan(''e,*", &info, SUBDIR, first)) 
{ 
first = 0; 
/* search only directories and skip "."" and ".." «/ 
if (Cinfo.attr & DIR) && Cinfo.name[0O] != '.')) 
{ 


/* pop into that directory */ 
chdirCinfo.name) ; 

/* search for the filenames */ 
Search()3; 

/x back to where we were = */ 
chdir(¢''..')3 

} 


Search() performs the recursive search described earlier. The major varia- 
tion is that the search is repeated for each of the file specifications given on the 
command line. This function depends heavily on the Scan) function, which 
proves to be very simple: 


/* 
* Scan() -> find a matching file 
*/ 
int Scan(name, info, attr, first) 
char *name; 
DIRINFO *info; 
int attr; 
int first; 
{ 
SETDTACinfo); 
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return (first ? FIRST(name, attr) : NEXT()); 
> 


This is the only occurrence of the three compiler-dependent macros shown 
earlier. Scan() could also be implemented as a macro, but is shown as a function 


here to simplify debugging and copying to another 


With the exception of the Handle() function (which decides whether some 
action should be performed on the current file), most of the whereis program 
has already been described. Before the various options can be applied to any- 
matched files, let us see how the options are parsed from the command line. 


Parsing Command-Line Options 


As we saw in good old main, the argument count argc and argument string vec- 


program. 


tors argv are passed to the ParseCommandLine() function. 


/* 
* ParseCommandLine() -> pick our options and filespecs 
*/ 
#define NEXTARG() Cif (!*++argp) Cargp=(*argvt++) sargc--;}} 
void ParseCommandLine(Cargce, argv) 
int argc; 
char *kargve 
{ 
char *argp; 
argc--; /* skip argv(0] */ 
argvtt; 
while Cargc--) 
{ 
argp = *argv++; 
if (*argp != '-') 
AddFileCargp); 
else 
{ 
argptt; 
switch (tolower(*argp) ) 
{ 
case ‘a' ; /* archive bit */ 
AttrMask |= ARC; 
break; 
case ‘d' : /* directory bit */ 


AttrMask i= DIR; 
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break; 

case 'v' : /* volume label */ 
AttrMask != VOL; 
break; 

case ‘'s' : /*® system bit */ 
AttrMask |= SYS; 
break; 


case ‘h' : /*x hidden bit */ 
AttrMask |= HID; 


break; 

case 'r' : /x read-only bit */ 
AttrMask |= RDO; 
break; 

case ‘b' : /* byte count */ 
NEXTARG(Q); 
if (C*xargp == ‘'-') j| C*argp == ‘+')) 

ByteFlag = (*argptt+ == '-') ? -1 3: 1; 

ByteCount = PickVal (&argp); 
break; 

case ‘t' ;: /* time stamp */ 
NEXTARG(); 
if (Ceargp == '-') |! (eargp == '+')) 

DateFlag = (*argptt+ == '-') 2? -1 3 1; 

DateStamp = Today - PickVal (&argp); 
break; 

case 'o' : /* origin directory */ 
NEXTARG(); 
TopDir = argp; 
break; 

case 'e' : /* execute */ 
NEXTARG(); 
Exec(nExecst++] = argp; 
break; 

default : 


fputs(''Usage : whereis [-advshr] [-b<n>]\ [-t<n>] 
e<command>] [-o<dir>] (files]...\n", 
stderr); 
exit(1); 
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The cryptic NEXTARG() is a very useful macro which allows for flexible spec- 
ification of the parameters of options. In essence, this macro states, “if there was 
no parameter given as part of the option string, move the argument pointer to 
the next argument,’ It is included within the ParseCommandLine() block to facili- 
tate copying to another program. ParseCommandLine() uses only one other inter- 
esting function PickVal(), which converts an ASCII string to a long integer 
representation: 


/* 
* PickVal() -> pick an integer from a string 
*/ 
long PickVal (p) 
char **p; 
{ 
long v; 


for (v = 0; isdigit(**p); ++*p) 
v = (v * 10) + (exp - '0'); 

return (v); 

} 


Handling Matched Files 


Now we are ready for the Handle() function: 


/* 
* Handle () -> handle a matched file 
*/ 
void HandleCinfo) 
DIRINFO xinfo; 


{ 
char theFile(128); 
int i; 


/* attributes 7? */ 
if (Cinfo->attr & AttrMask) != AttrMask) 
return; 
/* byte count */ 
if (ByteCount >= 0) 
switch (ByteFlag) 
{ 
case -1 : 
if Cinfo->size >= ByteCount) 
return; 


case 


case 


} 
/x date stamp 
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break; 

0: 

if Cinfo->size != ByteCount) 
return; 

break; 

13 

if Cinfo->size <= ByteCount) 
return; 

break; 


*/ 


if (DateStamp >= 0) 
switch (DateFlag) 


{ 
case 


case 


case 


+ 


-1 

if (FileDateCinfo->date) <= DateStamp) 
return; 

break; 

O: 

if (FileDateCinfo->date) 
return; 

break; 

13 

if (FileDate(info->date) >= DateStamp) 
return; 

break; 


DateStamp) 


/* a match, build the complete filename */ 


/x first 


the pathname */ 


getcwd(theFile, sizeof(theFile)); 
/* add trailing '\' if required */ 
if (*(theFile + strlen(theFile) - 1) != ‘\NV') 
streat(theFile, "\\'9D; 
/* add the filename */ 
strceat(theFile, info->name); 


/* execute any -e commands, otherwise print */ 


if (nExecs) 


for (i = O03; i < nExecs; i++) 
Execute(Execli], theFile); 


else 


puts (theFile); 


} 
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There are a couple of interesting points within the Handle() function: The 
comparisons inside the ByteCount and DateStampchecks are opposite. This is be- 
cause the “more than” tests have opposite meaning—greater than a certain size 
or before (less than) a certain date. The filenames matched are not printed if the 
“execute” option was selected. This is done purely for cosmetic reasons, so the 
filename does not interfere with the output of the executed program. 


Executing Commands on Matched Files 


For the actual execution of a command, the Execute () function handles the sub- 
stitution of the current filename for any occurrence of the '$' character: 


/* 
* Execute() -> execute command, substituting filename 
*/ 
void Execute(cmd, name) 
char *cmd, 
*name; 
{ 
char command(128), 
*CPp, 
*Np; 
cp = command; 
while (*cmd) 
if (*cmd == '$') 
{ 
np = name; 
while (*np) 
xcptt+ = *np+t+; 
cmd++; 
By 
else 
kcpt+ = *cmd++; 
*cp = 0; 
system(command); 
} 
Handling Dates 


MS-DOS provides two formats of a date—one format for describing the date 
stamp of a file, and another for describing the current date. The last two func- 
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tions of whereis convert these two date formats into absolute integers which can 
be compared. Both of these functions could be made considerably shorter. They 
are shown in this fashion only to demonstrate how to extract the date informa- 
tion: 


/* 
* FileDate() -> return file date as absolute integer 
*/ 
int FileDate(d) 
unsigned d; 


{ 

int days, /x days */ 
mons, /* months */ 
yrs; /* years ¥*/ 


yrs = d >> 9; 

mons = (d >> 5) & OxOF; 

days = d & OxtF; 

if Cyrs % 4) /* handle leap years */ 
dayst+; 

return (Cyrs * 365) + months(mons - 1] + days); 

} 


The Microsoft C library provides a number of time and date handling func- 
tions. However, they are all very general routines and as such consume a consid- 
erable amount of code. The following function uses the intdos © function to get 
the current system date directly from MS-DOS, saving several hundred bytes of 
code. This function also converts the system date to an absolute integer compati- 
ble with dates returned by FileDate(): 


/* 
* SysDate() -> return system date as absolute integer 
*/ 
int SysDate() 
{ 
int days, 
mons, 
yrs; 
union REGS rs 


r.h.ah = Ox2A; 
intdos(&r, &r); 
days = r.h.dl; 
mons = r.h.dh; 
yrs = r.x.cx - 1980; 
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if (yrs % 4) /* handle leap years */ 
dayst++; 

return (Cyrs * 365) + months(mons - 1] + days); 

} 


Neither of these functions is exactly correct, because they do not handle all 
of the variations of leap-year calculations. However, they probably will last well 
past the point where MS-DOS becomes obsolete, and thus may be considered 
“good enough.’ 


Compiling whereis 
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Due primarily to the simplicity of the program, compilation is also very simple. 
For the Microsoft C 3.0/4.0 compilers, the command line 


cl whereis.c 


is sufficient to produce a working version of whereis. If you desire an optimized 
version, I would suggest the following command, which provides maximum opti- 
mization: 


cl -Ox whereis.c 


Note that it is not necessary to include wildcard expansion subroutines (con- 
tained in the SSETARGV.OBJ file), because those are handled by the directory 
search functions, and we want them to receive exactly what was typed on the 
command line. 

You may have noticed that whereis was written without using either the 
printf© or scanf() functions. While it may have made for some cumbersome 
cade in one spot (the end of the Handle() function), including even the “no float- 
ing-point” version of print f() would have caused whereis.exeto be at least 2000 
bytes larger. 

This version of whereis makes no effort to handle any disk drive other than 
the current drive. It would be relatively simple to replace the chdir() function 
with a ChangeDriveAndDirectory() function that would allow the -o options to 
include a drive specifier. 

It was mentioned earlier that the filenames matched are not printed if the 
execute option was selected. The UNIX program findhas a -print option which 
controls whether matched filenames are printed, regardless of any other op- 
tions. Sometimes it is essential that the matched filenames be printed before a 
program is executed. It would be a rather simple programming exercise to adda 
~p option, indicating that matched filenames should always be printed. 
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Conclusion 


This chapter has shown you some techniques for accessing directory entries, 
and for navigating around tree-structured directories. We have also used both 
normal and alternate methods of calling MS-DOS from within a C program. 

The whereis program evolved in the same fashion as its UNIX counterpart 
find—out of a desire to find files and to do something about them when they 
were found. Professional programmers have found that whereis has become a 
useful file utility program—although it is small and simple, its power and versa- 
tility will allow you to perform tasks never before thought possible. 
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R. Edward Nather 


“Tis UNIX operating system was designed by computer programmers Ken 
Thompson and Dennis Ritchie for their own use, to provide a comfortable work- 
ing environment in which to write computer programs. Nonprogrammers find 
it hard to learn—it takes a while to get used to its terse, powerful commands and 
to get in tune with its underlying unity. Many critics of UNIX, who find it less 
than the ideal environment for business operations or secretarial work, seem to 
forget its original purpose. In my view, UNIX has been remarkably successful in 
achieving its original goal. It's the most convenient operating system I’ve ever 
used. This view is shared by many other programmers. I have yet to meet any- 
one who has become completely comfortable in a UNIX environment who pre- 
fers to use any other. If you've already used MS-DOS, installing PCnix on your 
computer can offer you a relatively painless way to learn more about UNIX and 
the real power it offers—and more about MS-DOS as well. 


Why PCnix? 


When I first got access to an IBM PC running MS-DOS (version 2.0), I was struck 
by the number of familiar UNIX-like features: command-line arguments, I/O re- 
direction, a hierarchical file system with directories, pipes, interpreted text 
scripts (batch files), a set of included software tools, etc. UNIX has clearly had a 
strong (but often unacknowledged) influence on MS-DOS—but so has another 
operating system: CP/M. The latest version of MS-DOS (3.3 at this writing) re- 
mains an unhappy hybrid of the two systems, with many UNIX-like features but 
with vestiges of CP/M as well. These seem awful to UNIX users—not necessarily 
because they are awful, but because they are different. The formal name for this 
problem is Semantic Confusion. The net result is that going back and forth be- 
tween UNIX and MS-DOS can be dangerous to your mental health. 
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There were several versions of “cut-down UNIX’ available at the time I first 
got access to an IBM PC, so I tried two of them and learned a great truth: the 
8088 is not a speedy microprocessor on the best of days, and, burdened with an 
operating system not hand-crafted to make best use of it, the result was unbear- 
ably slow. Also, most of the neat new software was being written in garages, 
haylofts, and universities for the MS-DOS operating system, and I wanted to be 
able to use it, while still enjoying a UNIX-like environment. 

Things are somewhat better today: the 80286 is a faster engine, and some 
commercial products offer a UNIX-like shell and a reasonable selection of soft- 
ware tools—but they can’t run all MS-DOS programs, and in particular are often 
baffled by memory-resident programs (TSRs). In general, they force you to give 
up your MS-DOS environment to get UNIX power into your PC. This is a sacrifice 
most PC users cannot afford to make. In addition, PCnix has the advantage that, 
unlike the commercial “UNIX for MS-DOS” products, it is fully customizable 
since you are provided with the source code for the system and most of its utili- 
ties. 

The PCnix system—essentially a collection of software tools that use the 
(unmodified) MS-DOS kernel—is my attempt to remove as many irritating differ- 
ences as possible, and to provide a comfortable working environment in which 
to write computer programs on the IBM PC. This design approach has some real 
advantages: 


f Complete MS-DOS compatibility is retained. (If you really prefer to use 
the DIR command rather than the UNIX command ls you can do it—just 
don’t tell me about it.) 


> It is fast even on floppy-based 8088 machines with enough memory for a 
modest-sized RAMdisk. 


> It offers the most-used UNIX software tools, and can be easily expanded 
by the user. New commercial and public domain versions of UNIX tools 
are continually being written and they can be easily added to PCnix. 


> Source code (in the C language) is available for almost all of the tools, so 
you can tinker with them as you choose and perhaps learn about C, 
UNIX, and MS-DOS in the process. 


To comply with government-sponsored truth in labeling, the disadvantages 
are: 


> Since it uses the MS-DOS shell COMMAND .CoM, it can interpret MS-DOS 
batch files, but lacks the ability to interpret UNIX-style shell scripts. 


Jt does not attempt to provide multitasking capability. 


> Some C programs developed under UNIX must be changed to run prop- 
erly under PCnix, where the system calls differ. 
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Overall, I think the advantages outweigh the disadvantages—but I may not 
be completely objective about it. In any event, let's explore what we must do to 
bend MS-DOS nearer to our heart's desire. 


Our Strategy 


Our mission is to provide MS-DOS with the ‘look and feel” of UNIX without serious 
compromises in response time, and without mucking about in the MS-DOS kernel. 
Let's first look at the basic problem we must face before we leap into action. 

UNIX supports a rich set of software tools, and people who use the system 
begin to think of problems in terms of the tools they have available to them—the 
richer the set, the more options they have in finding a solution. “To the man with 
only a hammer, everything looks like a nail’ We must be prepared to add the 
most-used UNIX tools to those supplied with MS-DOS. This is quite possible: only 
a few operations are internal to the MS-DOS shell COMMAND. COM; most are external 
commands, i.e., executable programs. We can replace any MS-DOS external 
command by replacing it with a program of the same name, or add a new com- 
mand by providing a program with a different name. However, the way com- 
mands operate under UNIX differs from what is possible under MS-DOS—UNIX 
is multitasking and MS-DOS is not. 

The UNIX toolkit is designed around the idea of pipes, where a string of 
separate tools works in sequence on a data stream, each tool doing its own thing 
and passing the result along to the next tool in line. For example, the command 
sequence 


cat names phones ; more 


will first invoke the cat command (concatenate the text files names and phones 
end-to-end); its output stream becomes input to the more command, which pages 
the text onto the display screen, pausing so the text doesn’t run off the top of the 
screen before it can be read. 

This command sequence, running under UNIX, will have both tools active 
at the same time—whenever there is any usable output from cat it is passed 
along to more right away, and immediately appears on the display screen. Under 
MS-DOS, which cannot handle more than one task at a time, cat must run to 
completion, storing its output in a temporary disk file. When cat is finished, the 
temporary file is read back from disk into more, whose output is (finally!) sent to 
the display screen. It may not take forever, but it feels like forever if you’re used 
to UNIX. PCnix can’t solve this problem in a general way, but we can design tools 
with a primitive more built into them so that they won't need to use a pipe, and 
can give much faster response. In general, we’ll need to tailor our tools to the 
MS-DOS environment in which they must run. 
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As a matter of principle, we want to do as little work as possible, so we will 
choose the simplest way we can find to provide any particular tool. If MS-DOS al- 
ready provides the appropriate tool (e.g., format) we'll use it unchanged; if not, we'll 
explore enhancing the tool's operation (and perhaps changing its name) by includ- 
ing it in a batch file (e.g., copy). If that doesn’t work, we'll try to find a suitable tool in 
the public domain. If all else fails, we'll write it ourselves, using the C language to 
code it in, and calling on the available MS-DOS services where necessary. 

Let's do the easy things first. 


Tweaking MS-DOS 
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In addition to providing enhanced, more UNIX-like tools for MS-DOS, we must 
make a few changes in the way it looks to the user. This involves getting MS-DOS 
to accept a more UNIX-like syntax. 

The simplest change to “raw” MS-DOS is to change the prompt. The com- 
mand 


prompt %4 


in the AUTOEXEC.BAT file turns the A> prompt into a UNIX-like % that already feels 
better—UNIX Bourne shell users might prefer $—but it has an awkward flaw: 
you can’t tell what drive you're on. 

UNIX has no notion of drive, since the complete file system looks like one 
huge inverted tree to the user. MS-DOS inherited the idea of drives from CP/M 
and still uses them, and it's important to know where you are in the file system, 
since it affects how you refer to a file you want to work on. If the file is not on the 
current drive, you must begin the name with the drive designator (e.g., a:) or 
MS-DOS can’t find it. As our first of many compromises, we use 


prompt $n%z% 


in the AUTOEXEC.BAT file to get the prompt C%if we are on drive C, A%on drive A, 
etc. 

Next we must change the path separator character from \ to / or every 
pathname will look jarringly different from its UNIX counterpart. MS-DOS, like 
CP/M before it, normally uses the / character to indicate a command-line option, 
or “switch,’ as in the MS-DOS command 


DIR /P 


where the option P asks that the DIR command pause at the end of the screen so 
you can read what it told you. UNIX, contrariwise, uses the / character to sepa- 
rate pathnames, and the character - to indicate a command-line option. Fortu- 
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nately, someone at Microsoft knew about this, and arranged MS-DOS so it can 
use either /or \ as a path separator, and you can change the switch character 
SWITCHAR if you know how. 

We first change the value of SWITCHAR that COMMAND.COM uses in parsing the 
command lines we type. By default, that character is /. If we use some other 
character to designate a switch, almost all of MS-DOS will let us use / in 
pathnames. The obvious choice is - which UNIX uses as a switch designator, but 
that choice has problems, too. 

Many PC programs use the - character as part of their names—PC-Write, 
for example. If we substitute - for the switch character, the parser in COM- 
MAND.COM looks for a file called pc and prepares to hand it the switch -W as an 
argument—not what we want. We can avoid this problem by referring to the 
filename as PC?WRITE but that subterfuge is too ugly to tolerate. We'll have to 
rename files that have - in their name. 

Alternatively, we can substitute \ as the switch character, in effect revers- 
ing the meaning of the forward and reverse slash characters. We'll have to re- 
member to use \ as a switch designator for those (few) MS-DOS programs that 
need a switch and that can’t accept - instead. This is the solution I prefer, but 
either way will work. MS-DOS 2.X allowed the switch character to be changed by 
including the line 


SET SWITCHAR=\ 


in the CONFIG.SYS startup file, but MS-DOS 3.X doesn’t. Undaunted, we use the 
(undocumented) Function 37h to fix things up; this works on all versions of 
MS-DOS starting with 2.0. A small program called INT37.CoM does this job right 
away in the AUTOEXEC.BAT startup file, so all subsequent pathnames can use / as 
the separator. Like UNIX, / by itself designates the root directory. 

Finally, since we want batch files to appear to execute the same as any other 
kind of executable command, we must do something about the ECHO operation, 
which decrees that all batch file commands are echoed to the console screen as 
they are executed. This gabbiness is particularly offensive to UNIX users, who 
come to appreciate the quiet way UNIX tools do their job. Even the mechanism 
provided to shut up this chatty behavior is flawed: the command ECHO OFF in a 
batch file is, itself, echoed to the screen, instantly betraying that a batch file, 
rather than some other type of command, is being executed. The latest version 
of MS-DOS (3.3) recognizes the @ character at the beginning of a line to mean 
“don't echo this line’; earlier versions must be patched. 

Each version of COMMAND.COM has a pair of flag characters that govern the be- 
havior of the ECHO operation, and by default, they are set ON. We want to set them 
OFF by default. Note that this still permits batch file commands to be echoed if that 
is desirable. Just include the command ECHO ON as the first command. The change 
only has to be done once to a copy of COMMAND. COM, and only the initial values of two 
internal flags are modified; COMMAND.COM is otherwise unaffected. 
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Using debug Scripts 


When PCnikx is first installed on a hard disk, the installation program (a batch 
file) calls on debug to fix COMMAND.COM, handing it a debug script with instructions 
about where the flags are and how to set them. What's a debug script? Glad you 
asked. 

The MS-DOS program debug can be used to create or modify executable 
files as well as to debug them. A few simple one-character commands, with argu- 
ments attached, is all we need to make a copy of COMMAND. CoMinto a friendlier and 
quieter shell. We can do it from the keyboard, of course—or we can prepare a 
set of commands, store them in a file, and call debug with standard input redi- 
rected so it comes from the file instead of the keyboard. The only tricky thing 
about writing such scripts is to note that debug understands the cr (carriage- 
return) code as a line ending, but is baffled by LF, the line-feed code. Scripts 
prepared by any self respecting MS-DOS editor will have their lines ended by CcR/ 
LF, the ill-chosen MS-DOS convention, so you'll have to take out all the LF codes 
(and comments) before debug will be happy with it. Not a terrible job, but annoy- 
ing. If you have a working copy of PCnix, you can remove the offending codes, 
and run the debug script, with the single command line 


tr -d \012 < file.dbs | debug newfile.com 


since the option -d tells the UNIX-like utility tr (transliterate) to delete octal code 
12, the line feed. 

The debug script used to modify COMMAND. COMin MS-DOS version 3.1 follows, 
with each command shown on a separate line: 


e 105b 2 ;change hex location 105b to the value 2 
e 1967 0 schange hex location 1967 to the value 0 
wW ;write the modified file 

q :quit 


If this script is stored in a file called fixcom.dbs (with all LF codes and com- 
ments removed, and lines ended by a single CR code), then the command 


debug command.com < fixcom.dbs 
will make COMMAND.COM a less irritating shell, automatically. A more extensive 
patch job is needed for DOS 2.X. 

The following procedure is used to shut up ECHO OFF in MS-DOS 2.x: 


1. Copy COMMAND.COM and debug.comonto a work disk. 
2. Execute debug command.comfrom that disk. At the - prompt, type 
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3. s 0 7fff 01 00 00 01; write down found _address + 3 as flag. 
Type 
4. s O 7fff 61 GE 64 20 70; write down found __address as patch. 
Type 
5. s 0 7fff B9 OA 00 E8; write down found__address as jmp. 
Type 
6. u jmp [substitute value found in step 5 for jmp). 
7. First instruction is MOV CX,000A, second is CALL yyyy - record yyyy value. 
8. a jmpt3 
CALL patch+1 


9. a patch 
DB 24 
ES: 
MOV BYTE PTR [flag], 00 
JMP yyyy 


10. w 
11. q 


Values found for different DOS versions are listed in Table 3-1. 


Table 3-1. Values for DOS Versions 


Value DOS 2.0 DOS 2.1 DOS 2.11 
flag 96E 96E 9B7 

patch 364A 365D 3886 

jmp 171D 1730 17E3 


yyyy 1E6D 1E80 2A10 


Improving MS-DOS Operation 


MS-DOS supports a system call of unusual power, Terminate and Stay Resident 
(TSR), Function 31h. It allows an executable program to remain in active mem- 
ory after it has been loaded, and protects it from being overwritten by other 
programs. (See Essay 7, Safe Memory-Resident Programming (TSR), by Steven 
Baker, for a detailed discussion.) The program can remain in memory through- 
out any computing session, up to the next computer reboot, ready to leap into 
action if called upon. We can use small programs of this type to add facility to the 
way MS-DOS does things without changing the MS-DOS innards in any way. 
There are lots of these additions available; PCnix uses two of them. 
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Much of the operation of MS-DOS is controlled by interrupts, and a table of 
pointers (interrupt vectors) is resident in low memory during normal operation. 
Any program can, at its own risk, replace one of these vectors so it will get called 
into action by the associated interrupt, then terminate but remain in memory. 
The program springs to life again whenever the chosen interrupt is triggered. 

The keyboards normally supplied with IBM computers or their clones al- 
low almost any keystroke to be repeated automatically just by holding the key 
down. Unfortunately, the repetition rate is very slow, chosen so novice users 
would not be frightened. This unfortunate hardware design choice can, fortu- 
nately, be corrected in software. 

The program qk.com is a version of the program quickeys.asm, written by 
Dan Rollins and published in PC Tech Journal (September 1986). It has been slightly 
modified for PCnix in order to remove a bug. Its only job is to watch for interrupts 
from the keyboard (one for each key action) and, when a key is pressed (and after a 
suitable pause), generate identical keystrokes at a much faster pace than the glacial 
rate provided by the PC keyboard itself, until the key is released. It is a small thing, 
but it makes any program requiring keyboard input seem much peppier. It works 
particularly well with PC-Write, the shareware editor. It is loaded automatically on 
bootup by the command ak in the AUTOEXEC.BAT file. 

The second TSR program, keydo.com, does much more, providing both a 
command history mechanism (like the UNIX C shell does) and a direct and simple 
way to edit the command line. Previous commands can be recalled by the up- or 
down-arrow keys on the PC keypad, while the other arrow keys move the cursor 
back and forth. The Home key puts the cursor at the start of the command line, the 
End key puts it at the end, and the Del key deletes characters. Any printable charac- 
ter typed is inserted in front of the cursor position. The (RETURN) key calls com- 
MAND.COM to execute the command no matter where the cursor is. Commands are 
stored in a circular buffer for prompt recall—they can be modified, or executed as 
is. Once you get used to it, you feel crippled without it. The public domain version 
used in PCnix was written by IBM programmer J. Gersbach, and is installed on 
bootup by the command keydo in the PCnix AUTOEXEC.BAT file. 


Using Batch Files to Create PCnix Commands 
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Text files whose filenames end in .BAT are interpreted by COMMAND. COMas execut- 
able commands, providing it can understand them. Although this facility is 
much more limited than the shell programming provided by the UNIX shells, it 
can still provide simple and useful services if two basic rules are followed in writ- 
ing batch files: 


1. Keep it short. 
2. No, it’s too long; make it shorter. 
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The COMMAND.COM interpreter is rudimentary but reasonably fast. It is often de- 
feated, however, by a curious self-inflicted wound: whenever it finds a batch file 
line that is an external program to be run, it runs it—overwriting the batch file in 
the process, which must then be reloaded before it can examine the next line. 
Keeping the batch files in a RAMdisk helps but is awkward to arrange. Still, if a 
batch file runs fast enough, it’s often the easiest way to add a simple command to 
the repertoire. 


Changing Names to Protect the Innocent 


The UNIX C shell provides a simple but powerful “alias” facility which allows you 
to rename a command anything you like. For example, novice UNIX users often 
complain about the terse and cryptic commands, such as ls or grep. Some users 
prefer to rename the commands to something they can remember more easily. 
Batch files can provide a simple alias facility as well. For example, the PCnix du 
command displays current disk usage via the batch file 


ls -asR 41 %2 43 %4 %5 46 KT KB 49 


simply by calling the |s command with suitable switch parameters. 


Commands Can Be Repeated 


Batch files are capable of far more than just calling a command by another 
name. They can improve the way a command operates to make it more useful. 
For example, the UNIX rmfile-removal command can be approximated by a batch 
file that calls on the MS-DOS (internal) command DELETEin a loop until it runs out 
of filenames to erase: 


sloop 

if "%1"" == """ goto end 
del 41 

shift 

goto loop 

send 


This emulation is simple, but not perfect. It permits deletion of a series of 
filenames, but it lacks the ability to delete subdirectories and their contents that 
the UNIX command rm-r * provides. Some may consider this an improvement 
rather than a defect, considering the havoc that can be wreaked from careless 
use of the UNIX rm. 
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Batch Files Can Be Subroutines 


If one of the commands in a batch file is the name of a second batch file, every- 
thing works, but in a chaining fashion; control is transferred to the second batch 
file but never returned to the first. This behavior has led several technical writ- 
ers to insist (erroneously) that you can’t call a batch file as a subroutine from 
another batch file. MS-DOS version 3.3 has a CALL command for this purpose, 
but earlier versions can get the same effect by simply invoking a new copy of 
COMMAND.COM to run the second batch file. Control returns to the original batch 
file when the second has finished: 


command \c second.bat 


Remember, PCnix reverses the / and \characters, so \c designates a switch, 
telling the new COMMAND. COMto quit when it has finished running its argument as a 
command—in this case, the second batch file. A copy of the current MS-DOS envi- 
ronment variables are passed along to the second batch file subroutine, but the 
copy is erased when it finishes, so it can’t just use the MS-DOS SET command to 
return strings to the calling batch file. There are ways, but they are ugly. 


Commands Can Be Combined 


As another example of a PCnix batch file command, one of the most-used opera- 
tions in UNIX (or MS-DOS) is to move to a new working directory (cd) and then 
display a listing of the files located in the new directory (ls). These two opera- 
tions are used so often it's worth combining them into a single command (ch). 
The UNIX command 


alias ch ‘cd \!*; ls -aFC } more’ 


defines this new command in terms of known ones; the cryptic notation \!*is C- 
shell shorthand for “all arguments on the command line’ In PCnix we do this 
same job with a batch file: 


if "41" == "as" goto fix 
if "41" == "bs"" goto fix 
if '"41"" == "cs" goto fix 
if "41" == "d:"" goto fix 
if "41" == "es'' goto fix 
if "41" == ""' goto fix 
ls 41 

cd 41 
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goto end 
fix 

cd 4“41/ 
ls 41 
zend 


Most of the verbiage in our batch file arises from the desire to allow the 
command to change the working directory on a designated drive as well as on 
the current working drive—a concept not present in UNIX. For example, if the 
batch file above is invoked with the command 


ch a:/usr/bin 
it will execute the PCnix commands 


ls a:/usr/bin 
cd a:/usr/bin 


which will first list all the files in the directory a:/usr/bin, and then change the 
working directory on drive a: to /usr/bin. If the batch file is invoked with the 
name of a drive but no path, then the root directory is understood to be the 
target, and the batch file provides the cd command with the root directory des- 
ignator /. The command also returns you to the root directory on the current 
drive when used with no argument at all, just as the UNIX cdcommand with no 
argument returns to the user's home directory. 

The most ambitious batch file command in PCnix emulates the UNIX cp 
command: 


if "2" == "" goto err 

if not "%2" == "' set INTO=%2 
if not "43" == '"'' set INTO=%3 
if not "44" == "' set INTO=%4 
if not "45" == "" set INTO=%5 
if not "%6" == "'"' set INTO=%6 
if not "47" == ""' set INTO=%7 
if not "%8" == '""' set INTO=%8 
if not "%9" == '"' set INTO=%9 
: loop 


if 41 == XZINTOX goto end 
copy 41 ZINTO% 

shift 

goto loop 

ferr 

echo Use: cp fromfile tofile 
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echo or cp fromfile (fromfile ...] todir 
send 
set INTO= 


The first line enforces the UNIX convention that cp must have at least two 
arguments. The MS-DOS convention that the second argument can be missing to 
designate the current directory “” is confusing in practice. The next series of 
tests scans the argument list, setting the environment variable INTO according to 
the last argument it finds. By UNIX convention, this should be a directory if more 
than one filename precedes it. The batch file hopes it is, but doesn’t check. (It is 
possible to check, using a “batch file helper,’ but that slows things down too 
much for simple copies.) 

Once the last argument is found, the MS-DOS copy command is called to 
copy the files, one at a time, into the file or directory represented by the string in 
INTO. The syntax %INTO%is known to the batch file interpreter, which substitutes 
the actual environment string for its name before executing the resulting com- 
mand. When the loop runs out of arguments, it terminates. The final line erases 
INTOas a matter of cleanliness. Again, the UNIX recursive copy cp-r *is not emu- 
lated. Some day... 


Batch Files Provide On-Line Help 


PCnix also contains a built-in help system with a simple syntax: helpalone gets a 
list of commands, and help xx displays a short description of command xx by 
searching a known directory for xx.doc. It is made up entirely of text files and a 
batch file driver help. bat: 


if "'%1"" == """ goto noarg 

if exist c:/help/%1.doc cls 
p c:/help/%1.doc 

goto end 

tnoarg 

if exist c:/help/help.doc cls 
p c:/help/help.doc 

send 


The command pis the PCnix equivalent of the UNIX more command. With- 
out arguments or redirection, it just sends the file to the screen, pausing after 22 
lines to keep things in view. The (RETURN) key gets one more line, (SPACE ) 
gets one more screenful. It displays an error message if it can’t find the file. 

PCnix contains a help file for each command. It shows the syntax—what 
you should type to make it work—then explains available options, describes in 
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general terms how the command works, and finally gives an example or two of 
its operation. Each text file attempts to fit within one screen and is successful for 
the simpler commands. As an example of the format of the help documents, the 
following shows the text of the file tail.doc, which is displayed if you type the 
command helptail. 


tail - display the tail end of a text file's contents 

Syntax: tail (-####] filename [filename ...] 

With only the filename as an argument, ‘tail’ displays 

the last eleven Lines in a text file. With more than one 
filename, it displays the last eleven lines of each file 
successively. Two will just fit on one screen display; this can 
be handy in comparing two versions of a text file. With a numeric 
argument, ‘tail’ displays the number of requested lines 

at the end of the designated file(s). By default, output is 
displayed on the console screen, with a pause every 22 Lines. 
<RETURN> displays one more line, any other key displays the 

next screenful. The pause does not occur if output is redirected 
to a file or device. A huge numeric argument will display the 
complete text file. Binary files give a funny looking display but 
nothing burns. 


Examples: 
tail text Display the Last 11 Lines of "text." 
tail -123 xx > yy. Extract the last 123 lines of file "xx" 


and deposit them into a file called "yy." 


Using Batch File Helpers to Increase Flexibility 


Batch files have no direct mechanism for making system calls to MS-DOS, but 
since they can run an external program (at some cost in time) we can add this 
capability. All that is required is a short program to make the needed system call 
and a way of returning the result so the batch file can test it. MS-DOS provides a 
crude return mechanism: if the program exits via the interrupt Function 4Ch, 


the value in the AL register is preserved and can be tested by the if errorlevel 
construct. 


Creating Short Programs 


Probably the simplest way to write a short program is to use debug interactively 
to create it as a .COMfile. Here's the procedure to use: 
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. debug newfile.com (Debug responds File not found and creates it) 
. a (Debug now accepts commands to assemble) 

Type the commands in sequence (addresses will start at 0100h) 

. Type (RETURN) to make an empty line 

. rex (Debug responds Cx 0000 bytes, then prompts with “:”) 


anf OW DY 


. Type the (hex) number of the empty line address (line 4), after sub- 
tracting 100h. 


W 
8. q 


As an example, here’s what your screen shows when you create INT37.COM 
to set the SWITCHAR variable to /as described earlier (except for comments follow- 
ing vu): 


debug int37.com 


File not found * Debug creates int37.com, grumpily 
-a ; start to assemble 

1166:0100 mov dl,5C s put ‘'\’ code into register DL 
1166:0102 mov ax,3701 : Function number 37h to AH, 1 to AL 
1166:0105 int 21 : AL == 1 means set SWITCHAR from DL 


1166:0107 mov ax,4C00 : Exit with errorlevel set to 0 
1166:010A int 21 


1166:010C ; empty Line tells Debug to stop assembly 
-rex examine the CX register 
cx 0000 Debug response: current value is 0 


3C 
-W 
Writing OOOC bytes 
-q 


empty_line_address - 100h 
write number of bytes in CX 
Debug response 

quit. 


=e ee Se te Be 


If you are adept at using the assembler MASM, you might prefer to write 
batch file helpers in assembly code, which is easier to document and maintain. 
They are usually so short, though, that using debug is much faster. 


Taming the SUBST Command 


Many useful programs for the PC were written when MS-DOS was young, be- 
fore it knew about directories; these programs assumed everything was availa- 
ble directly on one of the drives. In UNIX parlance, all the files were stored in the 
root directories. This was tolerable before hard disks entered the scene, but 
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with 10MB or more of storage available, a DIR command became a real adven- 
ture. The hierarchical directory system, eerily similar to the one used in UNIX, 
was added to MS-DOS 2.0. This solved one problem but created another: the 
older programs only worked if the directory they were stored in was the default, 
an awkward requirement to realize with a single (hard disk) drive. Since we want 
to be able to use these older programs under PCnix (and have them look just like 
the newer ones), we must solve this problem somehow. 

MS-DOS 3.0 provided a partial solution in the form of the su8ST command. 
This command allowed any directory to be designated as an honorary drive, de- 
fined by its pathname. Now the older programs could be located anywhere, and 
a batch file could be designed to make them operate as if they understood about 
directories. It almost worked. 

Let's examine how to write a batch file to call the IBM program Wordproof 
into action. This excellent program looks up words in its dictionary and stops on 
any it can’t identify, letting the user verify or change the spelling. It can suggest 
possible spellings (or synonyms) on request. For convenience, we'll put Word- 
proof in the directory /edit/spell. We can use suBST to call this directory drive e:, 
for example, so when we want to proofread the file we've been working on in 
our current directory, c:/propose/draft, we can say 


cd e: 


to go to /edit/spell. Now we want to call the Wordproof program into action with 
draft as an argument, so . . . oops. That file is on the drive c, the one we just 
came from, not drive e. Can't do it that way. 

Well, OK, let's call the program from our working directory, with the com- 
mand 


eswp draft 


so Wordproof can find it—but now Wordproof can’t find its own dictionary, be- 
cause it looks only on the default drive when it starts up. 

We could assume we'll always be working from drive c and wire that idea 
into the controlling batch file, but that means we can’t proofread a file that is on 
a floppy disk in drive a. 

The right way to do it, of course, is to find out what drive we are on before 
we go to our mythical drive e, then use that information to tell Wordproof where 
to find the file to proofread. We can then return to our original working direc- 
tory when we are done. MS-DOS knows what drive we are using, and even has a 
function call to tell us—if we could make such a call from our batch file. With a 
batch file helper, we can. Consider this small program: 


; drv - return current drive number as errorlevel 
mov ax,1900 ; get current drive number (function 19h) 
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int 21 
mov ah,4C ; return AL as errorlevel (function 4C) 
int 21 : int 21h does almost everything ... 


MS-DOS Function 19h returns the current drive number (0 = a, 1 = b, 
etc.) in the AL register, just where Function 4C expects to find the errorlevel 
value. If we create this program as drv.comusing debug, we can include it in our 
batch file proof .bat: 


drv 

if errorlevel 0 set DRV=a: 
if errorlevel 1 set DRV=b: 
if errorlevel 2 set DRV=c: 
if errorlevel 3 set DRV=d: 
subst e: c:\editp\spell 

e: 

wp ADRVAA1 

*DRVA 

set DRV= 

subst e: -D 


First we call drv.com, then put the name of our current drive in the environ- 
ment variable DRV. (The errorlevel test is a bit strange: if errorlevel 1 tests true 
if the errorlevel value is equal to or less than 1. Reversing the test order would 
leave the wrong value in DRV.) Next we create our phantom drive and go there, 
where Wordproof lives. The string %DRV% will be replaced by the string we stored 
in the environment, so if we typed the command 


proof draft 
the command that calls Wordproof into action becomes 
wp c:draft 


if our original working drive was drive c. Similarly, after Wordproof finishes its 
job, the next line will be 


Cs 


which returns to the directory draft is in. As a final bit of cleanliness, we remove 
orV from the environment and delete the connection between e: and c:/edit/ 
spell. 
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Syntactic note: the shiny new suBSTcommand stubbornly refuses to look at 
SWITCHAR for its switch character, so it insists on \ as a pathname separator. To 
delete the established connection, it demands the 0 switch (and requires that it 
be uppercase!). But it will accept neither \ nor / as the switch character if 
SWITCHAR has been changed. It does accept - however, a fact missing from the 
MS-DOS documentation. 


How Many Drives Are Out There? 


PCnix can run comfortably on a two-floppy system, providing it has enough 
memory to hold a RAMdisk of reasonable size—640K is nice. The most-used 
commands are written to the RAMdisk on system startup, with the help files and 
less popular commands residing in directories on floppy drive a. Startup is a bit 
slow, but if the RAMdisk is the default directory, most commands take less time 
to run than from a hard disk. A lot of floppy-swappy goes on, though, if you try 
to do something serious such as run a compiler. A hard disk is better if you can 
afford one. 

PCnix uses a public domain RAMdisk system written by Nat White; it has 
the advantage of being able to be removed (well, set to zero capacity) without 
rebooting. The driver, ram.sys, must be included in the CONFIG.SYS file used dur- 
ing startup. It does need to know the name of the drive it pretends to be, though, 
and this depends on how many real drives are installed in front of it. Here’s the 
batch file helper used to find out about the drives present: 


; ldrv - return index of last valid drive 


mov bl,20 ; assume no more than 32 drives 

mov ax , 4404 ; IOCTL call, read from block device 
mov cx ,0000 7 number of bytes to read (none) 

int 21 

dec bl ; count down in BL 

cmp al,OF ; IOCTL returns OF if drive invalid 
jz 0102 ; if so, try the next smaller one 
mov al,bl ; else BL now has the index 

mov ah,4C ; return with index as errorlevel 
int 21 ; O means A, 1 means B etc. 


The portion of the AUTOEXEC.BAT file that creates the RAMdisk and then fills it 
with commands from the floppy disk looks like this: 


?tind out drive name for RAMdisk 
Ldrv 
if errorlevel 2 set RD=C 
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if errorlevel 3 set RD=D 

if errorlevel 4 set RD=E 

path %RD%4:/;a:/binja:/system 

echo Creating a RAMdrive as drive “RDA: ... 

setram ARD%: 256 

echo Copying the most-used commands to drive #RD&: ... 
copy a:/toram/*.* “ZRD%: > nul 

set comspec=4RD%: \command.com 


Note that MS-DOS will insist you have two drives even if there is only one 
physical drive installed. This is actually ingenious, since two drives are simulated 
by the system by using the one real drive alternately. The command 


copy a: a: 


works just fine, prompting you to change source and target disks as needed. In 
any event, Ldrv will never return 0 or 1 as the last valid drive index if ram.sys has 
been loaded. 

Once the drive name is known (and stored in the environment as Rb), the 
name %R0% can be used wherever the drive name is needed—as the first direc- 
tory searched (after the current one) via the PATH command, as the target of the 
copy command, and as the location for COMMAND.CoM, should the latter get over- 
written and need to be reloaded. 


Taming the MKDIR Command 


PCnix installs itself onto a hard disk from a batch file, which creates directories 
(bin, help, etc.) on the hard disk to hold everything. Should the directory already 
exist, the installer should quietly put files into it—without complaint. The 
MS-DOS command MKDIR, however, gets upset if the directory already exists, and 
complains with an error message that cannot be redirected into the NULL file— 
the usual way of shutting things up. In this case, we need to know whether a 
particular name is already present as a directory, so we create a batch file helper 
to tell us: 


: fd - find out if arg string is the name of a subdirectory 
mov bx ,0081 : psp address of arg string start 
add bl, (0080) number of chars in string 


' 
mov byte ptr (Cbx],00 3; null-terminate the string 
mov dx ,0082 ¢ point to 1st non-blank char 
mov ax, 4300 : get filename attribute 
int 21 
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mov ax,4C00 ; return errorlevel exit 
cmp cx,+10 ; is it a directory? 
jn2z 0118 ; if no, return 0 

inc AX ; if yes, return 1 

int 21 


We assume that the string was given to the fdcommand as an argument, and has 
been installed by COMMAND. CoMin the usual place for the first command-line argu- 
ment. The string format is different from that expected by MS-DOS Function 
43h. (Naturally—consistency is a virtue of the small mind.) So, we must first con- 
vert it, then call on the system to see if it is the name of an existing directory. We 
convert the returned attribute into a yes/no answer and return it as a testable 
errorlevel. 

Here’s a portion of the PCnix file instal .bat that uses this helper, reading 
from a floppy disk in drive a: and installing the system onto drive c: 


a:/bin/fd csbin 

if not errorlevel 1 mkdir c:bin > nul 

echo Filling directory "bin" with PCnix executable files ... 
copy a:zbin bin > nul 


Is There a Clock in the House? 


As a final example, PCnix tries to read the clock/calendar via its AUTOEXEC .BAT file 
on bootup. In a brave attempt to be independent of the hardware that might be 
present, it tries several “readclock” routines for different types of hardware. It 
depends on a batch file helper to find out if it has been successful in reading the 
clock. If not, it keeps trying until it runs out of things to try. If it is successful, it 
writes a short code string into the environment to tell other routines what kind 
of clock is present, in case they need to know. It knows it’s running on a PC/AT 
clone if the clock is correctly set before it tries anything. 

Here's the helper that finds out if the (internal, MS-DOS) clock has been 
properly set: 


; tclk - test to see if clock/calendar has been set 


mov ah,2A 3; Get date 

int 21 

mov ax, 4C00 ; O -> AL, "return errorlevel" -> AH 
cmp cx,07C3 ; is date less than 1987? 

jl 010E ; if yes, clock is not set 

inc ax ; else mark it as set 

int 21 ; return AL as errorlevel 
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Figure 3-1 summarizes our discussion of the design of PCnix by showing 
how the parts of a typical PCnix system are arranged. Notice how the batch files 
and software tools used by PCnix fit into the MS-DOS environment. (See Essay 1, 
Harry Henderson's Guided Tour inside MS-DOS, for a discussion of how the parts 
of MS-DOS interact.) 
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Fig. 3-1. How PCnix and MS-DOS fit together. 
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The Software Toolkit 


We've created our basic PCnix environment and the easy support routines; now 
we have some real work to do. MS-DOS provides several software tools that are 
specific to its own file system. We can adopt those tools that do a good and useful 
job (FORMAT, DISKCOPY, CHKDISK, SYS), and we can scour the public domain for oth- 
ers. Even so, we'll fall far short of the nifty tools provided by UNIX—so we'll just 
have to write them. We'll adopt the C language as the most portable and UNIX- 
like, using a commercial compiler (Microsoft C or Borland’s Turbo C) as the clos- 
est approximations to the Portable C compiler (cc) that comes with our particu- 
lar UNIX system, Berkeley UNIX 4.3bsd. 


Tools for Dealing with Text 


Our plan is to avoid slavishly copying the UNIX toolkit in every detail. We must 
take into account the different operating environment provided by MS-DOS, and 
use its services as much as possible to make things speedy. We'll start by dividing 
the tools into groups, and we'll tackle first those tools concerned mostly with 
manipulating text—the primary medium of exchange between the various UNIX 
software tools. Table 3-2 lists those in PCnix. 


Table 3-2. Text Tools 


Tool Function 

ed PC-Write, a powerful, modeless editor for word processing 
diff Find minimal differences between two text files 

eline Enforce MS-DOS line-ending convention on a text file 
grep Search text files for patterns, print all lines that match 

p Display files, optionally with visible control codes 

pr Page and print text files, optionally in multiple columns 
split Split a long file into shorter segments, gracefully 

sr Search and replace multiple text patterns in parallel 

str Find the ASCII strings in a binary file 

tail. Display the tail end of a file's contents 

tr Transform a series of (single) character codes into others 
uniq Remove (or print) duplicate lines in a text file 

wc Count lines, words, and characters in a text file 


We'll need an editor to create and edit text files. PCnix really doesn't care 
what editor you use, so long as it creates normal ASCII text and runs under 
MS-DOS. The shareware editor PC-Write is a good one, and a PC version of the 
Berkeley UNIX editor vi is available commercially. PCnix also uses the nansi.sys 
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public domain replacement for the MS-DOS display driver ANSI.SYS, written by 
Dan Kegel, because it's faster. | 

Some of the text tools do the same jobs, and therefore bear the same 
names, as their UNIX counterparts: diff, grep, pr, tail, tr, unig, and we. A few 
are different, or have different features, in order to cope better with MS-DOS. 
For example, text lines under UNIX are ended with a single code LF. MS-DOS 
requires two: CR/LF. CP/M uses only one: CR. The et ine tool can cope with alien 
line endings, substituting the MS-DOS cR/LF convention for whatever it finds. If 
no line-ending convention is found, it word-wraps at the end of a line whose 
length can be specified (default 80 columns). Its ability to word-wrap (but with- 
out any attempt at hyphenation) makes it a useful companion to the pr program, 
which can produce two (or more) columns of text, but chops the ends off text 
lines that are too long. 

The p (pager) program has a couple of hidden talents in addition to paging 
text to the display screen. It can strip out high-order character bits inserted by 
some other text programs, most notably WordStar, thus converting the output to 
a printable form. If its output is redirected into a disk file, it behaves like the 
UNIX cat command. It can also substitute printable codes for the eight codes not 
normally printed by the nansi.sys screen driver (Null, Tab, Bell, Backspace, CR, 
LF, Escape, Rubout), so you can see what they are. It uses intensified characters 
to distinguish them from their unintensified look-alikes. Printing a binary file to 
the screen is quite entertaining but the results are not terribly informative. 

In a more practical vein, the str program searches through binary files and 
displays any text strings it finds. This action is similar to the UNIX program 
strings except it knows about the various different kinds of text strings found in 
MS-DOS. UNIX, bless it, has only one style. Strange things can sometimes be 
found in executable files. For example, if you scan a new program fresh from a 
BBS and encounter a string like HAHA, GOTCHA! !!!!, don’t run the program. 

Now, let's choose one of the text tools and examine it in some detail. The C 
language encourages a program architecture consisting of many separate func- 
tions, each of which does a logically complete job. If these functions are written 
with some attention to modest generality, they can often be used unchanged in 
subsequent programs. Since we've already seen the help.doc file describing tail 
let's see how that command works. Here are the separate routines in outline 
form: 


tail - display the tail end of a text file’s contents 
allnum - examine a string for numeric characters exclusively 
toscreen - find out if output is to the console screen 
filecopy - copy the Last part of a file to stdout 
stak - a circular data storage & retrieval structure 
size ~ set the modulus size of the circular stack 
push - overwrite the oldest stack entry 
pull - extract the oldest available stack entry 
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(pop - extract the youngest stack entry) 
endlin - end a line and watch for screen overflow 


The main routine, tail.c, processes the command line options—in this 
case only one option may be present, the one to set the number of lines to be 
printed. It calls on al tnum.c for help with that chore. It also calls toscreen.c to 
see if the output is going to the display screen or not. If it is, tail.c sets a global 
flag (tsc) so the output will pause after each screenful of text. tail.c next opens 
any files on the command line it can find, calling on filecopy.c to do the dirty 
work for each one of them: 


/* toscreen — find out if output is to console screen */ 
finclude <dos.h> 


toscreen() 

{ 

union REGS r; 

r.x.ax = 0x4400; /* get IOCTL status code */ 
r.x.bx = 13; intdos(ér, &r); 

return((r.x.dx & 1) && (r.x.dx & 0x80)); /* isdev && iscin */ 
} 


The function toscreen.c shows the way C can be used to make MS-DOS sys- 
tem calls and return the result. The #inc ude file dos.his a header file that defines 
REGS to match the registers available in the 8088 microprocessor. All C compilers 
available under MS-DOS have this facility, but there is no standardization, so the 
PCnix tools try to isolate this activity, minimizing the number of routines that have 
to be changed if some other compiler is used. ANSI, where are you? 

The filecopy.c routine makes use of a very UNIX-like feature of MS-DOS. 
Files are treated as simple strings of bytes; with text files, one character is stored 
in each byte. System calls allow the pointer that indicates the next character to 
be moved around—just like a memory pointer. The file characters need not be 
read-only in the order they are stored. By putting the file pointer to the file's end, 
filecopy.c can determine how many characters the file holds, and can then 
move back the number of lines requested and display them. 

There is one complication: how many characters (bytes) are there on each 
line? It varies with the text—in fact, some files may not be text files at all, so we'd 
best be careful here. If we want to move back 11 lines from the end (the default 
value), we can move back 880 characters and be reasonably safe, since we dis- 
play at most 80 characters on a line. Now we'd like to move forward in the file, 
watching for line-endings and counting them until we come to the end again. If 
we keep track of just where we found each one, we can go immediately to the 
start of the eleventh line from the end and print from there. 

The filecopy routine calls on a circular storage buffer to do this last job, 
setting its length to the number of requested lines—in our example, eleven. It 
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then proceeds to examine the file one character at a time, using the push oper- 
ation to store a character count for each line-ending found. If there are more 
than 11 lines, as there may well be, the oldest counts are overwritten. When the 
end-of-file is found, the desired character count will be the eleventh count from 
the end. The pull © operation extracts it since it is the oldest value present. (The 
pop() operation—extract the most recent value—is included for completeness 
but is not used here.) 


#define FHOME O /x symbolic constants for fseek */ 
#define FHERE 1 

#define FEND 2 

/*x filecopy - copy the last part of an open file to stdout */ 
filecopy (fp) 

FILE *fp; 

{ 

extern long lines; 

int c, le = 0; 

long nchars, guess, acnum; 

long pull); 

sizeClines + 2); /* size stack, allow for trailing newline */ 
guess = lines * 80; /* estimate no. of chars this represents */ 
fseek(fp, Ol, FEND); 


acnum = ftell(fp); /* find how many there really are */ 
ifCacnum <= guess) 
guess = acnum; /* use the smaller number */ 
fseek(fp, -guess, FEND); /* rewind to that point */ 
nchars = ftell(fp); 
while((c = fgetc(fp)) != EOF) { /* and run forward */ 
nchars++; 
if€c == '\n') ¢ 
lot++; /* counting text lines */ 
push(nchars); /*x and save corresponding char no. */ 
} 
} 
if(le >= Lines) 
fseek(fp, pull (), FHOME); /* rewind to requested point */ 
else 
fseek(fp, -guess, FEND); /* or to best guess */ 
whileC€(c = fgetc(fp)) != EOF) /* and send it out */ 
if(€c == ‘\n' && endlin()) /*x watching for display pause */ 
continue; 
fputc(c, stdout); 
} 
} 


Chapter 3: Adding UNIX Power 


Under UNIX, we could just pipe the output through more to page it one 
screenful at a time, but that’s much too slow under MS-DOS. Instead, we'll in- 
clude the subroutine endlin.c in each tool we write that sends text to the 
screen. 


H#define SCRSIZ 22 
/* endlin - end a line and watch for screen overflow */ 


Static int le = 0; /* Line counter */ 

endlin( 

{ 

extern int tsc; /* true if output is to screen */ 

register int c; 

if(tse && ++lc >= SCRSIZ) { /* pause if output is to screen */ 
fputs ('\r\n\03307m--More--", stdout); /* and a screenful */ 
c = bdos(7) & OxFF; /* get a keystroke */ 


fputs("\033COm\r\O33(K", stdout); 
switch(c) ¢ 


case ‘\r': /* <RETURN> - show 1 more Line */ 
lc = SCRSIZ - 1; 
break; 
case ‘q': /* quit with "q'" or "ctrl-C"! */ 
case '\003': 
exit (0); 
default: 
lc = 0; /* else show another screenful */ 
break; 
} 
return(1); /* yes, we ended this line */ 
} 
return(Q); /* no, we didn't end it */ 


} 


The strange codes in the fputs function are understood by the MS-DOS 
screen driver nansi.sys; they paint --More--in reverse video, on a line of its own 
below the text lines. The function then waits for a keystroke, which it examines 
to see what to do next. When it finds one, it either quits or returns a code indi- 
cating whether it had to stop (and thence end the last displayed line) or not, and 
erases the --More-- from the screen. The caller must supply the line-ending 
codes if the subroutine did not. 

An external flag (tsc) indicates whether the output is going to the screen or 
not. This is very useful to many tools. If output is redirected into a disk file, or to 
the printer, it can be passed to them uninterrupted. The flag can be set correctly 
for any execution of the tool by calling toscreen() once, as was done here by 
tail.c. 
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If you are curious about the circular storage buffer, it’s surprisingly simple: 


/* stak - a circular data storage & retrieval structure */ 
H#define EMPTY -1 


long *s = NULL; /* holding stack */ 
unsigned int lp = 0; /* lifo index */ 
unsigned int fp = 0; /* fifo index */ 
unsigned int endm = 0; /* modulus Limit */ 
/x size - set the mod size of the stack & allocate space */ 
size (i) 
int i; 
{ 
if((s = Clong *)malloc(i * sizeofClong))) != NULL) 
endm = i; 
} 
push(x) /* overwrite the oldest stack entry */ 
long x; 
{ 
sClp++] = x; 
if(lp >= endm) 
lp = 0; 
if(lp == fp) 
fp = ++fp % endm; 
} 
long pull) /* extract the oldest available stack entry */ 
{ 
long j; 
if(lp == fp) 
return(EMPTY) ; 
j = slfpl; 
fp = ++fp % endm; 
return(j); 
} 
long pop() /* extract the youngest stack entry */ 
{ 
if(lp == fp) 
return(CEMPTY) ; 
if(--lp < 0) 
lp += endm; 
return(s(lp]); 
} 
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Dealing with Files 


The PCnix toolkit also includes a set of software tools for listing, finding, and 
manipulating files. Table 3-3 lists the current repertoire. 


Table 3-3. PCnix File Tools 


Tool Function 

arc Compress and archive files, or decompress files 

dog Reorganize your hard disk for fastest access 

chmod Change the mode of a file to/from system, hidden, etc. 
chn Change the name of a file, directory, or volume label 
du Summarize disk usage in a part of the file hierarchy 
ffind Find path{(s) to filename(s) on the designated drive 

ls List filenames in a directory, in many nice ways 

mv Move files or directories to another location 

pwd Print full path to current working directory on a drive 


The file compressor/archiver/decompressor arc is a shareware program, 
distributed by System Enhancement Associates, that first examines a file, then 
chooses one of several compression techniques depending on what it finds. Text 
or binary files can be compressed 30 percent to 50 percent, a helpful saving if 
the file is destined for transmission over phone lines. 

The disk organizer dog, written by G. Allen Morris III, is also distributed as 
shareware. It explores your hard disk and then, with your permission, reshuf- 
fles the way storage clusters (clumps of disk segments) are ordered on the disk 
to paste together all the files that have become fragmented (stored in several 
pieces) by the MS-DOS storage system. This can speed up subsequent disk-inten- 
sive operations dramatically. It can take a long time to run, but it keeps you enter- 
tained with a slightly breathless account of how the job is progressing. Run it 
during lunch break. 

The UNIX program findcan be dispatched into the file system to look for (and 
perhaps modify) files you name or describe on the command line. It is a very pow- 
erful tool only UNIX gurus use, because the syntax is unbelievably painful. It's a 
superb example of a program that tries to do too much. Our PCnix program f find 
has a much more modest mission: it explores a file system on a designated drive 
recursively, peeking into each subdirectory and listing the complete pathname to 
any file we tell it to watch for. It can accept the MS-DOS wildcard characters, so we 
can find all the batch files on drive c, for example, with the command 


ffind c:*.bat 


It's marginally useful on floppy disks and almost essential on hard disks with 


81 


Section 1: Extending the MS-DOS User Interface 


82 


20MB or more of storage—it’s amazing how easy it is to misplace files even in a 
well-organized directory system. (See Essay 2, Searching the File Tree with 
whereis, by Frank Whaley, for a utility more like the complete UNIX find com- 
mand.) | 


What’s in a Name? 


MS-DOS 2.X had a curious limitation: its rename command, which called on Func- 
tion 56h, worked on files but not on directories. To change a directory name, 
you first had to create a new (empty) directory with the chosen name, copy all 
the files from the old one into the new one, delete the old files, and then delete 
the old directory. On a floppy disk, you would always run out of space about 
halfway through. Yet, MS-DOS Function 17h could rename directories. It did not, 
however, understand about pathnames. Our PCnix chncommanzd is a short pro- 
gram that calls Function 17h, accepting the limitation that the designated file 
must be in the current directory of one of the drives. 

MS-DOS 3.0 quietly introduced a new version of Function 56h that can re- 
name directories (without, of course, mentioning that fact in the documenta- 
tion). Our mv command can use this new capability to rename directories, but it 
can’t do so under MS-DOS versions before 3.0. We'll also teach mv about drives. If 
a file or directory is moved to another location on the same drive, only the File 
Allocation Table (FAT) need be changed, and Function 56h will do that for us. 
Moving files or directories to another drive requires that everything be copied to 
the new, then (if the copy is successful) erased from the old. mv does it that way. 


What's in a Directory? 


Perhaps the most-used command in either UNIX or PCnix is the ts command, 
which tells us the names of files in one or more directories, and as much about 
them as we ask for—unlike DIR, which tells everything it knows whether we ask 
or not, shouting at us in UPPERCASE. The ls command has (perhaps too many) 
options available to control what it does: 


ls - a UNIX-like directory listing program for MS-DOS 

Syntax: ls C-acilrstuR] ((path)name ... ] 

Options may appear in any order, grouped or separated; if 
separate, each must be preceded by a dash. The name(s) may refer 


to files or directories. If no name is given, the current 
directory is listed. MS-DOS wildcards are graciously accepted. 


Chapter 3: Adding UNIX Power 


Options: 

(none) Show filenames Conly) sorted alphabetically 

“a all: include system files, hidden files, "." and ''.." 

-c columnar: change how many columns are used in the Listing 
~i identify: change whether directory pathname is shown 

-t long Listing: include file's size, date, time, attributes 
-r reverse the sorting direction 

“Ss report size(s) only 

=t sort by time of last file modification 

-u include actual disk use, with totals & available space 

-R recursively list all subdirectories 


The default settings for most of these options can be changed, so Ls can be 
sweetened to taste. For example, some people like to have the name of the cur- 
rent directory shown, along with its contents, when ls is invoked without argu- 
ments—in effect, UNIX pwd followed by (s. Others find this offensive. If it matters 
to you, you can change one or more of the “customizing constants” in the pro- 
gram to change the default settings from those normally supplied: 


/* customizing constants */ 


#define ID 1 /* always identify directory if 1 */ 
#define ALL 0 /* show hidden files by default if 1 */ 
#define LONG 0 /* long listing by default if 1 */ 
H#define SCOLM 0O /* 1-column short listing by default if 1 */ 
H#define LCOLM 1 /* 1-column long listing by default if 1 */ 
Hdefine RSORT 0 /* reverse sort by default if 1 */ 
Hdefine TSORT 0 /x time sort by default if 1 */ 
#define DU 0 /* include disk use by default if 1 */ 


Since \s has to poke around in the MS-DOS file system, much of its opera- 
tion involves making system calls to learn things, and reformatting the result 
(e.g., transforming filenames to lowercase) for display. In outline form, here are 
the various routines that make up the whole, with MS-DOS function calls identi- 
fied in parentheses: 


ls - a UNIX-Like directory Listing program for MS-DOS 
main - process input options 


toscreen - find out if output is to console screen (44h) 
setps - set pathname separator to MS-DOS switchar value (37h) 
curdrv - get name of current default drive (19h) 
curpath - get path to directory on default drive (47h) 


search - search ‘path’ for filename or directory 
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find_first - find first file in chosen directory (1Ah, 4Eh) 
comp - compare size of two entries for quicksort 
gcdate - get current date (months) for comparison (2Ah) 
getcl - get cluster size & space left on A drive (36h) 
abspath - get absolute path into search path buffer 
find_next - find the next file in this directory (1Ah, 4Fh) 
(calls the same routines as find_first) 
shortlist - print a list of names in up to 5 columns 
putname - convert name to lower case and print 
endlin - end a Line and watch for screen overflow 
Longlist - list everything about files in one or two columns 
fill - fill long List structure with file information 
mname - convert month number to month name 
putname - convert name to lower case and print 
endlin - end a line and watch for screen overflow 


Table 3-4 lists a few other tools to complete our toolkit. Fortunately, a com- 
plete version of the wonderful UNIX utility make for MS-DOS has been distrib- 
uted as shareware by its author, D. G. Kneller—it is superior to the “professional” 
version distributed by Microsoft with its C compiler. We'll add the touch com- 
mand to work with it, calling Functions 2Ah and 2Ch to get the current time and 
date, then calling Function 57h to insert them into the file's time-stamp. 


Table 3-4. Hacker Tools 


Tool Function 

make Compile, link a C program from separate files, minimally 
tglob Transform global definition file into extern decl file 

touch Mark the time-stamp of a file with the present date/time 
kermit Terminal emulator and file transfer utility 

uuencode Encode a binary (executable) file as ASCII text 

uudecode Recover the original binary from encoded text files 

now Display the current day, date, and time 

switch Display or change DOS SWITCHAR character (default is \) 
xp Expand wildcards in filenames and display all that match | 


We'll use the excellent Kermit protocol for file transfer to and from our Vax 
(running UNIX, of course) written by Frank da Cruz, and distributed at cost by 
Columbia University. We can make use of its MS-DOS version to pretend our PC is 
actually a smart terminal—Kermit has terminal emulation built in. We'll also use 
the public domain programs uuencode and uudecode, written by Mark Horton, so 
we can send binary files over phone lines. Kermit handles binary files correctly, 
but many electronic mail programs get serious indigestion from nontext code 
combinations. The uuencode program transforms a binary file into an encoded 
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text file, and uudecode recovers the original binary file at the other end. The orig- 
inal filename is preserved. By convention, beerbust.uue is an encoded file and 
should be fed to uudecode, which might produce beerbust .arc as its output. The 
command 


arc x beerbust.arc 


will extract the individual files from the transmitted archive, binary or other- 
wise. 

Our miscellaneous category includes now, which tells you what now is, 
switch that permits changing SWITCHAR as a last resort in getting a program to 
run, and xp, an MS-DOS version of the UNIX EcHOcommand. The UNIX shell pro- 
grams expand the metacharacters ? and * for each program they invoke, but 
COMMAND. COM does not. Under UNIX, the command 


echo *.txt 


will echo to the screen all filenames in the current directory that end in .txt, so 
you can see what will happen if you use, instead, 


rm *.txt 


The xp command does this same job for MS-DOS. 

But what is that program called tglob? Well, it’s a programmer's tool—a bit 
specialized, perhaps, but handy when we write large C programs like ls. The C 
language demands that global filenames be defined, and optionally initialized, in 
only one place. The normal convention is to #include them in the main.c pro- 
gram. All separate subroutines must know about them to use them, however, so 
they need the same list of names, but listed as external declarations. Keeping 
two name lists is both tedious and error-prone. The final goody in our “friendly 
programming environment” project PCnix is the help file for tglob: 


tglob - transform global definition file into extern decl file 
Syntax: tglob (filename) > outfile 


Global variables may only be defined in one place in a C program, 
but must be referenced as "extern" declarations in all other 
files that use them. "tglob" acts as a filter, to transform a 
global definition file into another file with the necessary 
"extern" declarations present, and with any initializing 

values removed, so only the definition file need be maintained. 
With no filename present ''tglob"' reads its standard input; it 
always writes to stdout. Using a makefile, the following 
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dependence entries will create a new declaration file from the 
definition file, automatically: 


sglob.h : glob.h 
tglob glob.h > sglob.h 
where "glob.h'"' is the definition file, and "sglob.h'" is 
the resulting declaration file. The main program file should 
contain #include "glob.h" 
and all separate subroutine files should contain 
#include 'sglob.h" 


Example: Before Cinput to tglob): 


oe 8 8 008 ne 0 0 no a 0 0 8 0 ee ee ee en ee ee ee i 
SO a a a ee Se ae a Se Se DS Oe ae a a ae ee ae ae ee ee Oe ee ee De SD OD OD OD OD SD OO OD a a aD ae an ae a ae a 


/* individual field lengths for full and reduced display */ 
int box1 = 4; 
char ffmaxl]={0,8,9,0,19,19,19,19,19,0,8,19,2,0,6,6,6,6,0,3,0,0}; 
unsigned char wbuf1[) = 
" REKKKKKKKKKKKKKKKKKKKKKKKKKKKKKE\ F\N\ 
* 02:07:13 UT *\r\n\ 
* 23 Jan 87 *\r\n\ 
HH KIKIRERRERERERERIIRREIREREERRE\ P\ 
char *mo[] = { 
"Jan", "Feb", "Mar","Apr',"May","Jun",""Jul', "Aug", "Sep, "Oct", 
"Nov", "Dec! 
3; 
int ftimel40); /x filter change time array */ 


8888888 88888 28 88 8 SS SS SF O88 OO St SS 8 Se ee eee we eee we wwe 
Fe a ee Se Se SD NG Ca ES CD SS SF a a a Sa Se Oe es SS ES ED SD SS DS Cae ee ae ee are SD GS nS Gs OD GD GD DD a Oe eo ee oe 


/* individual field lengths for full and reduced display */ 
extern int box’ ; 

extern char ffmax[] ; 

extern unsigned char whuf1[] ; 

extern char *mol] ; 

extern int ftimel]; /* filter change time array */ 


eS 2 OS 82 OBO OB BC OO BS ee ee en we a 
ee ee a as a as ae a ee re ee a ee ee ee ee ee ee ae oe et ae ee ae waa a aca aa a as ao 


MS-DOS Wildcards Are Not UNIX Metacharacters 


Although the wildcard characters ? and *in MS-DOS (and hence in PCnix) are, at 
first glance, the same as the ? and * metacharacters in UNIX, there are real dif- 
ferences that can cause you grief. Basically, the filenames in MS-DOS consist of 8- 
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character (max) filenames, optionally followed by a dot (.) and a 3-character 
(max) extension: 


wildcard.doc (longest possible filename in MS-DOS) 


If you move a file from UNIX, be sure the name follows MS-DOS rules. As an 
ugly example, if you copy a UNIX file called wildcard.doc2 to MS-DOS, it be- 
comes wi ldcard.doc. The extension is truncated to 3 characters and the file may 
overwrite one Called wildcard.doc if one is present in your working directory. 

The ? metacharacter in UNIX matches any one filename character, just as 
in MS-DOS. In UNIX, however, 7??? matches any 3-character name but not any 
one- or two-character names. In MS-DOS, ??? matches all filenames with one, 


in MS-DOS that has no extension, and the construction ??77?777.??? matches 
any possible name. 

The * metacharacter in UNIX matches any sequence of filename charac- 
ters, as it does in MS-DOS, but there is an important difference. Wherever +* is 
found in a filename, MS-DOS replaces it with as many ? characters as will fit, up 
to the dot character or to the end of the extension. If you are in the habit of using 
* on UNIX to avoid typing long filenames, look out. The UNIX command rn «ff 
would remove any filename that ends in ff but in MS-DOS the same command 
removes all files that lack an extension. Similarly, the UNIX command rm*ff.*gg 
removes only those filenames that end in ff and have an extension ending in gg. 
In MS-DOS, the same command removes all files in the current directory! In 


dot character and ??? afterward, so the ff and gg exceed the allowed filename 
length and are truncated and thrown away. 

The danger is that some things work the same on both operating systems 
and some do not. For example, rm abc* removes only those files that start with 
abc on both systems, and have no dot or extension. But rm*.* removes all files in 
the current directory in MS-DOS, and leaves those files in UNIX that do not have 
the dot character in their name somewhere. MS-DOS does warn you by asking 
Are you sure (Y/N)? whenever it encounters ??7???77.22?? (perhaps expanded 
from *.*), so if you get this warning when you were not expecting it, say NO. 

Table 3-5 lists some MS-DOS examples, and what they mean. 


Table 3-5. MS-DOS Examples 


Command Function 


rm ???.,* Remove all files with one-, two-, or three-character filenames, with or 
without an extension 

rm ?.??? Remove all files with one character filenames, with or without an exten- 
sion 


rm *any.??? Remove all files in the current directory 
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Epilogue 


PCnix is not UNIX, and doesn’t try to be. It adopts, with grateful acknowledg- 
ment, many of the really good programming ideas embodied in the UNIX operat- 
ing system and its accompaniment of software tools. It brings a comfortable 
UNIX-like environment to the IBM PC and its clones. It has been embraced by 
many who go back and forth between a UNIX system and a PC—and, surpris- 
ingly, by a few who have never used UNIX. 

So what is the UNIX operating system? Is it a kernel surrounded by soft- 
ware facilities to provide multitasking capabilities to a large number of users 
simultaneously? If so, PCnix isn’t even in the same ballpark. Yet PCnix feels a lot 
like UNIX to a user—in a blind test, a UNIX guru worked away for over 20 minutes 
before he discovered he was really talking to MS-DOS. (He was furious.) 

So perhaps UNIX—or the heart of UNIX—is just a collection of software 
tools that work well together, and provide a comfortable and convenient working 
environment on a computer. PCnix has no pretensions beyond that modest goal. 


The PCnix software collection will be available in two formats: execut- 
able code only, which takes up about three 360K floppy disks; and ex- 
ecutables plus all available source code, which needs about six. The 


current system loads itself onto a hard disk and runs comfortably under 
MS-DOS version 3.1; other versions of MS-DOS or other computer configu- 
rations may take some setup work on your part. For more information, 
contact R. E. Nather; P.O. Box 27007; Austin, TX 78731. 
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Pee Essay Synopsis: Every programmer is 


aware of the amount of repetitive and te- 
dious work involved in developing an 
MS-DOS application. Menus, help screens, 
data entry screens, and perhaps dialog 
boxes and windows all have to be designed 
and implemented. Routines for indexing. and 


accessing data have to be written. MS-DOS 

- itself offers little help in these areas, since it 
provides only a rudimentary batch-process-°. 

- ing capability and no screen generation, 


windowing, or data management facilities. . 


_ In recent years, however, many products 


have been developed to add power to 
MS-DOS programming. This essay looks at 
three representative products in detail and 
shows you how they can solve program- 


_* ming problems. Extended Batch Language 


(EBL) provides sophisticated batch process- 


__ ing to automate programming tasks, and 
_. amounts to a full-featured programming’ 

_ language in its own right. Vitamin C makes 
~. it easy for C programmers to do the attrac. 

‘tive screens and windows users expect to-.. 


day. Finally, C-INDEX uses indexed files with | 
easy-to-use data management routines that 
can be used with any C program. 
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Programming 
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Douglas O. Adams 


Win each new version, MS-DOS has become a more powerful operating sys- 
tem, but many programmers do not use its features to the best advantage. There 
are many techniques and tools you can use under MS-DOS that will make pro- 
gramming faster and more convenient. We will look at some typical problems 
encountered by the MS-DOS programmer and show how to overcome them. 
Since the C language is becoming the primary PC programming language, we 
will use C for our examples. If you are not a C programmer, similar tools are 
available for other programming languages. 

Once the environment is set up and running, how do you run a group of 
commands or programs consecutively as a batch? Most operating systems allow 
users to put a group of commands into a file so they will be executed consecu- 
tively or conditionally. This feature allows commonly needed operations such as 
compilations and file backups to be performed without repetitive typing. On 
UNIX systems, this is called shell programming and on large IBM systems it is 
called C Scripts. MS-DOS currently supports a similar, but more limited, facility 
called batch or .BAT files. 

Most operating systems for larger computers provide support for screen 
generation and data entry for application programs, but as recent as several 
years ago, few such tools were available for personal computers, and PC pro- 
grammers had to write their own screen and data entry code for each project. 
Due to their speed and single-user support, very fast screen operations are pos- 
sible on a PC, but programming PC screens in most languages is a very time- 
consuming and error-prone process. 

Organized information storage presents specific challenges: a list of names 
needs to be available alphabetically, invoices need to be accessible by number, 
scientific weather data may need to be ordered by date and time. Early com- 
puter systems sorted massive amounts of data to achieve this accessibility. A 
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newer technique, indexes, provides a way to order and select data in a much 
more efficient manner. 


Setting up Your Operating Environment 
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Many users want their computers to set certain parameters and install device 
drivers each time the system is booted. As you probably know, a CONFIG. SYS file 
allows you to do this. This file is executed by MS-DOS automatically each time 
the system is booted, and can include instructions to add additional devices and 
modify certain DOS defaults. Such a file might include 


DEVICE = MOUSE:SYS (turn on mouse driver) 
DEVICE = VDISK.SYS 128 /E (set up RAMdisk memory) 
FILES = 20 (allow more open files) 

BUFFERS = 20 (increase disk buffers) 


The mouse device driver will work as soon as the system is started. The 
second line in the file defines a virtual disk using extended memory beyond the 
640K size limit to simulate a disk drive. The MS-DOS default for the maximum 
number of open files is 8 files. Since this is not enough for many compilers to 
operate, we extend the number of open files to 20 by including FILES=20. Buffers 
are used for holding information being read from or written to disk files. 

The DOS command buFFERS= lets you set the buffer size from 1 to 99, with 
each number equaling 528 bytes. The default setting is BUFFERS = 2 or 1024 
bytes. For an XT class machine, the setting should be BUFFERS = 6. For an AT 
class machine, BUFFERS = 20 is generally suggested. Although this means the 
DOS will use more memory, file operations will generally run much faster. 


Using AUTOEXEC.BAT to Get Started 


As you probably know, DOS provides AUTOEXEC.BAT, a special batch file which 
should be placed in the main directory along with COMMAND.COM, and will auto- 
matically be executed when you boot your system. It is usually used to execute a 
series of programs that you want to run each time you start up the system. For 
example: 


PATH=\; \MW\PROG; \UTIL\DISK\DOS; \UTIL\MISC; \UTIL\SHANC 
PROMPT Sp$g 

RETRIEVE 

CD \UTIL\DO 
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dO 
MENU 
CD\ 


The first line sets the path with a list of subdirectories. Any program or .BAT 
file in the listed subdirectories may now be run from any other subdirectory. This 
is useful for frequently used utility programs or a word processor that may use 
text files in many different subdirectories. The second line changes the prompt to 
display the current path (name of the drive and subdirectory now active), making 
it easier to keep track of where you are in the directory hierarchy. Next, a mem- 
ory-resident program RETRIEVE is run. This program maintains a stack of DOS 
commands for later use and also lets you edit the DOS command line. 

Some programs, including many compilers, need to access overlays or data 
files in order to run. Since the PATH command does not establish access to any 
data files, the line CD \UTIL\D0is used to change the current path to another sub- 
directory where the program 00 is run. DO is a calendar-scheduling program 
called Daily Organizer that runs automatically each time the computer is turned 
on. The program is necessary to change the current directory so 00can find the 
data files it uses and expects. The last program run before changing the path 
back to the main directory is a customized MENU program. 


Benefits of the Menu System 


Using a menu program to run commonly used applications has three benefits. 
First, it saves having to remember the exact name of each program and type it. 
Second, it saves having to awkwardly change the current directory. Finally, it 
makes it possible for people with little knowledge of MS-DOS to use the com- 
puter effectively. For example, the following batch file is named MENU. BAT: 


CD \UTIL\MENU 
MENU 
CD\ 


This simply changes the subdirectory, runs a program named MENU. COM, 
and then returns to the main directory. If MENU.BAT is placed in a subdirectory 
that is listed with the PATH command, it can be run from any current subdirec- 
tory. Incidentally, if you use such batch programs, be sure to place them in a 
subdirectory included in the PATH so they will always be available. Many power- 
ful menu programs are available if you should choose to use one. Figure 4-1 sum- 
marizes the use of the files and programs we have discussed for setting up your 
environment. (Harry Henderson's Essay 1, A Guided Tour inside MS-DOS, evalu- 
ates the MS-DOS user interface and programming environment and has further 
suggestions for improving it.) 
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Fig. 4-1. Setting up your environment. 


Almost everything described will work with any version of MS-DOS that is 
2.0, or later, but version 3.0 adds the VDISK.SYS command and version 3.3 adds 
APPEND. The latter allows access to data files similar to the way the PATH com- 


mand provides access to programs. 


Using Extended Batch Language for Real Power 


Extended Batch Language (EBL) is a program from Seaware Corporation of Del- 


ray Beach, Florida. It offers the following features: 


= operating batch files faster 


™, 


= accepting messages from the user 
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i* creating attractive DOS screens 
creating help screens using DOS 
-- passing information on to programs 
*~ performing arithmetic expressions and assignments 
“~ parsing strings for special handling 


“- searching for files to see if they exist 


DOS processes batch files by reading them from the disk one line at a time. 
Each line is executed and another disk access is required for the next line. This 
results in very slow processing. EBL speeds up the processing of batch files by 
reading the entire batch file into memory before its execution, allowing you to 
set a buffer size that can be as large as 64K. This buffer is then used to hold all 
batch files currently in use. 

The batch command set is considerably expanded, and additional com- 
mands allow you to provide a number of operations beyond the minimal ones 
offered by MS-DOS. While many of these commands are very easy to use, a 366- 
page manual and a bulletin board service are available for assistance from the 
program's developers. Let's begin with a simple example using EBL: 


BAT CALL HELP.TXT 
BAT PAUSE 
BAT CLS 


The first line uses CALL to display a regular text file. This can include in- 
structions, warnings, or any other information you want to present to the user. 
PAUSE is a regular DOS batch command which will hold the text on the screen 
until the user presses a key, and CLS, of course, clears the screen. The BAT at the 
beginning of each line identifies it as an EBL command. 

EBL provides full control over the screen to create an attractive and helpful 
user interface. You can create menus, display text and help screens, draw boxes, 
and change colors—all with ease. While DOS batch commands do not allow any 
user responses, EBL lets you ask the user questions or make selections. This is 
very important when you need to accept a selection or filename from the user. 
Another simple example would be to read in a filename to execute with your 
word processor: 


BAT /P 
TYPE Enter the name of the file to process: 
READ %7 
WORD %7 


Notice that we began the program this time with /P after the BAT. We can 
now eliminate the BAT prefix to all the other commands. TYPE is standard DOS. 
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But the READ command is new. It allows us to read a string from the keyboard 
and assign it to the variable %7. MS-DOS allows batch variables in the range from 
%0 to %9. EBL extends the batch variables by adding the range from %A to %O. 
The last line of our example starts Microsoft Word with the file specified in 47. 
This example may seem trivial, but you can devise much more complex sets of 
instructions that require user input to carry out a sequence of operations. 

String-handling operations, arithmetic expressions, and assignments can 
be performed on the user responses. File searches can be conducted and pro- 
gram return codes can be checked. All these operations allow you to branch to 
the appropriate part of your batch program and to provide error messages 
when needed. 


EBL Commands 


The basic EBL commands are listed in Table 4-1. They are used in batch files to 
display data, accept keyboard data, and control the logic flow of the batch pro- 
gram. Each command performs a simple operation, defined beside the com- 
mand. They are used in a similar way to the language used in C and Pascal. 


Table 4-1. Basic EBL Commands 


Command Function 

BEEP Sound speaker 

BEGIN/END Delimit block of commands 
BEGSTACK/.END Add data to keyboard stack 
BEGTYPE/END Display text 

CALL Invoke another batch file 

CLS Clear the display screen 
COLOR Change text color 

EXIT Leave batch program 

GOTO Branch to a label 

IF/THEN ... ELSE... Conditional statement 

INKEY Accept single keystroke 
LEAVE Stop EBL and continue DOS 
PARSE Separate string into variables 
READ Accept response, assign to variable 
READSCRN Get variables from screen 
READ.PARSED Read and parse 
READSCRN.PARSED Readscreen and parse 
RETURN Return from a CALLed subroutine 
SHELL Execute DOS command 

SKIP Skip number of lines specified 
STATEOF Check for existence of a file 
STACK Pass input to a program 
STACK.LIFO Put messages on stack 

TYPE Display messages or variables 
* 


Batch file line is a comment 
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Control functions and directives (see Table 4-2) provide additional control 
over EBL batch files. They are used to determine how EBL will operate. 


Table 4-2. EBL Control Functions and Directives 


Function or Directive Operation 
CALL.PURGE Clear CALL/RETURN stack 
STACK.ON Turn stack on 

STACK.OFF Turn stack off 

STACK .PURGE Clear user response stack 
TRACE.ON Turn on debugging mode 
TRACE.OFF Turn off debugging mode 
file Write file 

) file Append file 

> Close write 

file Read file 

« (file Reopen file 

« Close read 

IK Kill EBL batch processing 
/L LEAVE default 

IP No BAT Prefix 

1Q Permit strings to use quote marks 
MR Run new file 

IS SHELL default 

fU Uppercase 

BIOS or RAM Set display writing mode 


EBL expands the number of variables from the 10 provided by DOS to a 
total of 26 under EBL (see Table 4-3). It also provides additional special purpose 
variables. 


Table 4-3. EBL Variables 


Variable Function 

%0 to %9 DOS variables 

%A to %O EBL Global User variables 
%Q Returns stack status 

%R Stores MD-DOS return code 
%S Space Literal 

%V Default Drive 

%% “%" Literal 

%NAME% Environment variables 


Error-recovery processing is made possible by two commands which allow 
you to provide special instructions or processing when an error occurs during 


97 


Section 1: Extending the MS-DOS User Interface 


98 


the operation of an EBL batch file: -ON. ERRORindicates branch to label if an error 
occurs; RESUME indicates branch to line number on the error. 

EBL provides an additional 25 external functions for the advanced pro- 
grammer. They are called external because they reside in three separate .COM 
programs that can be activated if needed. These functions provide advanced 
string-handling, system-status inquiries, low-level system control, and floating- 
point arithmetic. 


Unlocking Your Storage with EBL 


Imagine a fairly typical problem: you have several disk drives and you know that 
your word processor and a text file are somewhere on the system. But where 
are they actually stored? The following EBL program (supplied by Seaware Cor- 
poration when you purchase EBL) will find them for you and begin execution. 
The program first locates which diskette the editor is on, then locates the file 
you want to edit, and finally starts the editor with the appropriate file. Lines 
starting with an asterisk (*) are comments. Begin with 


A> EDIT MYFILE.DOC 


EDIT will invoke a batch file named EDIT.BAT. MYFILE.DOC is the name of the word 
processing data file that you want to edit. If the EDLIN editor were on drive A 
and the file MYFILE.DOC was on drive B, this EBL program would create the fol- 
lowing DOS command: 


A> EDLIN B:MYFILE.DOC 
The listing for the EBL batch file follows: 


BAT /p 

* LISTING OF "EDIT.BAT" 

* Enter here the name of editor to call: 
%0 = EDLIN 


* Make sure editor is somewhere 

STATEOF %0.COMAc 

IF XR <> 1 SKIP 4 

STATEOF %0.EXEXb 

IF £R <> 1 SKIP 2 

TYPE The %0 editor could not be found on any drive! 
EXIT 


* Setup drive # where editor really is: 
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IF AR > O XO = &R:%0 


* Search for the file to be edited... 
4C = 
STATEOF %12%C 
IF £R > 9 SKIP 3 
TYPE The filename to edit is invalid. 
TYPE Reenter command... 
EXIT 
IF 24RD 1 41 = &C 
STACK 40 41 K2 43 44 XS %6 X7 XB OO 
EXIT 


First, assign the name EDLIN to a variable %0. Next, the STATEOF command 
looks for a prefix of EDLINand a suffix of .coMor .EXE. The IF statement checks for 
a valid return code. The return code after performing a STATEOF command is al- 
ways returned in the variable (%r. If a file is not found, the return code will be 
equal to 1. The program will fall through to the TYPE command which will display 
an error message. If the file is found, the program will SKIP to EXIT. If the editor is 
found on another drive, the drive is changed in the IF %R <> 0 %0 = RR: %O line. Next, 
we look for the file to be edited, using the STATEOF command once again. Note that 
if XR equals 9, the filename is invalid. This could occur with an incorrect disk drive 
designation or with a filename which did not follow the MS-DOS conventions. A %R 
return code of 1 indicates that the filename was valid but that the file was not 
found. In this case, the argument is set to %C which is blank. The editor will be 
started but no file will be opened with it. The STACK command passes data to 
MS-DOS as though it came from the keyboard. Here, it is used to actually execute 
the edit program with the specified file. Using this command eliminates the need 
to return to the batch file after the editing is completed. 

In summary, EBL is a fairly complete programming language that lets you 
quickly write batch files that can take the place of compiled programs. Since they 
do not require compiling, they are much faster to write and test. EBL commands 
also offer system-level features which other programming languages do not. 


Programming Screen Control Facilities 


Early computers used a teletype machine as the terminal. It operated exactly like 
a typewriter, handling one character at a time. CRT display screens were very 
rare. Today, with the universal use of CRT display screens capable of displaying 
many lines of data at a time, new techniques for screen display are necessary. We 
want increasingly powerful capabilities on our display secreens—windows, color, 
and simple editing of data fields. 
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You may have discovered that the C language (and most other languages on 
personal computers) has no built-in facilities for handling data fields on the 
screen. Most computer systems larger than PCs offer features to simplify the 
development of display screens. These features may be part of the operating 
system or add-on packages. The IBM System/36, for example, offers as part of its 
Control Program (operating system) the ability to create a menu system and in- 
formation display screens that edit and format. 

Larger computer systems use a variety of packages to offer these features. 
On IBM mainframes, CICS (Customer Information Control System) is widely 
used to develop such screens, serving as an interface between the programming 
language and the operating system. It reduces the amount of code the program- 
mer has to write, and even more importantly, provides a standard interface be- 
tween different programs, thus making program changes and maintenance 
easier. CICS also provides a consistent interface to make it easier for users to 
learn new applications. Other hardware manufacturers offer similar facilities 
for their systems. 

Taken a step further, Fourth Generation languages exist both on PCs and 
large computers. Programs such as Paradox for PCs and IDMS for mainframes 
offer fast ways to develop screens, once you have mastered the tools. These pro- 
grams both include database facilities, however, which may not be required or 
suitable for your application. 

There are simpler, still very powerful, tools for PC screen development. 
These work in conjunction with another programming language such as C, Pas- 
cal, or COBOL. Since we are focusing on the C language, we will discuss one 
particular C screen tool: the Vitamin C (VC) library. 


Libraries for the C Programmer 


C was developed with the specific goal of making it a general purpose language 
that could be easily used on many different computers. This portability was 
achieved by providing a small language with no input or output facilities. In it- 
self, such a language would be useless, of course, but the implementers of C 
determined that all input and output would be done by linking the C code with 
code from an easy-to-use library for each specific machine. These I/O library 
functions can be used within a C program like any other function. All C compil- 
ers are shipped with a standard I/O library for some computer, provided for by 
the #include stdio.hinstruction in the C program. The emerging ANSI standard 
for C specifies the minimal set of functions each compiler should provide. 

The standard I/O library is very limited in its capabilities by today's stan- 
dards. The VC library is much more powerful than the one shipped with your 
compiler and just as easy to use. Simply incorporate the VC functions into your 
C source code program, using an #include statement. While you link your pro- 
gram to the C libraries, you include the VC object code libraries in your com- 
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mand to the MS-DOS linker. The linker locates the necessary VC functions and 
incorporates them into the object code (see Figure 4-2). VC is an excellent prod- 
uct for program development using the C language. 


Source Include 
Cod Files 
Cc 
Libraries 


MS-DOS 
Linker 


Vitamin C 
Libraries 


EXE 
Program 


Fig. 4-2. Using Vitamin C. 


Features of Vitamin C 


VC offers many features. Some of them you may use every time you write a pro- 
gram and some you may use rarely, if at all. The following are available with VC: 
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creating a data entry or display field 

using the standard IBM editing keys for data input 
providing the user with a request for data 
providing help screens linked to fields 

controlling color and other text attributes 
validating and formatting data input 

providing up to twelve windows on the screen 


VVVVVVVY¥ 


simple, but powerful text editing 


Advanced I/O Routines 


The C language provides limited facilities for controlling the placement of data 
on the screen. How do you overcome this basic problem in order to create data 
fields that are easy to edit by the user? You could spend months writing these 
routines yourself, but VC provides them for you. 

Information entered into a computer is usually structured into fields of 
data or freeform text. VC handles both types of information. Fields of data rep- 
resent specific information, and can be displayed to the user or used to request 
input from the user. To display a field on the screen you would use the command 


atsay(row, col, string); 


where the row and column are integers indicating placement on the screen. The 
string may be a constant or a variable. Thus 


atsay(12, 40, "This is the center"); 


will be displayed on the 12th row and begin in the 40th column, printing the 
message shown. 

It is equally simple to request input from the user. The following command 
uses field for the name of the variable holding the string and picture for op- 
tional formatting of that string: 


atget(row, col, field, picture); 


The next problem is how to make sure that the user has entered the correct 
type of data. The picture part of the command allows you to build a template of 
acceptable input. The following symbols, used in the picture, indicate which 
type of data is acceptable: 


x 


any key 


any key with uppercase alpha conversion 
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a = only alpha 

A = only alpha with uppercase conversion 
9 = numbers entered from left to right 

# = numbers entered from right to left 


The # sign lets the display act like an adding machine with the digits moving 
to the left as each digit is entered. You can also include formatting characters in 
the picture template. To bring this all together, let’s use a simple example where 
we want the user to enter a telephone number, making sure only digits are en- 
tered. We also want to supply the parentheses for the area code and the hyphen 
for the local number automatically. The following code will do all this: 


atget (6,20, phone,"'(999) 999-9999": 


Special characters such as a decimal point, comma, floating dollar sign, or 
asterisk-filled field can be used for money amounts. The entire set of symbols 
gives you a lot of flexibility. 

Now comes the best part of all. If you create a form on the screen, all the 
special keys on the IBM keyboard work just the way you would expect (see Table 
4-4). 


Table 4-4. Key Functions in VC 
Cannes SS 


Key Function 

LEFT ARROW Move cursor left 

RIGHT ARROW Move cursor right 

INSert Toggle insert mode 
DELete Delete character at cursor 
UP ARROW Move cursor up 

DOWN ARROW Move cursor down 

Home Move to the first field 

End Move to the last field 

Pgdn Move to the next page 
PgUp Move to the previous page 
F1 Display help text for field 
F2 Move or adjust window size 
ESC Quit input and lose data 


Moving through the form to the last field ends the input normally, allowing 
the program to save the data. All of the values above can be changed by the pro- 
grammer if you have special data entry requirements. However, these default 
operations can save you a lot of special coding and provide your programs with 
an excellent user interface. Since the keys will always work the same way 
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throughout your programs, the user will learn how to use them much faster 
and find them easier to use. 

A character's attribute indicates how it is displayed. Attributes include 
color, underlining, and blinking. The setattr() function can be used at any time 
to change or add attributes. 

Although it is easy to create a form with labels, a label of just the word 
“Date:” might not be meaningful to the user. What date is requested and what 
format is required? Vitamin C allows you to provide instructions for each field 
on a special status line using the xatget () function. When the cursor is moved 
into a field, the status line provides additional information on the field. We will 
use date in the following example: 


xatget (6,0,name,''99/99/99" ,NULL, 
"Enter date of purchase", 
NULL, vc.dft, vc.dft); 


The format (slashes) will appear in the screen field, and the message "Enter 
date of purchase" will be displayed whenever the cursor is within this field. The 
descriptive information can be provided for each data field on the screen with 
no extra programming—all cursor management is handled for you by VC. The 
string constant can also be a pointer to a string assigned elsewhere in your pro- 
gram. In this example, NULL and vc.dft are defaults for other optional control 
fields. Since we do not now want to use these special features, we fill the argu- 
ments with default values. An optional function isblank() will require the user 
to enter something into the field before continuing on to the next field. 

Usually, the picture will provide sufficient control over the data being en- 
tered. However, a validation capability also gives the ability to provide your own 
data-editing functions. If we substitute editdate() for the first NULL in the com- 
mand above, our function editdate() will be called when the user exits the field. 
Thus, we have the capability for any type of editing needed if we are willing to 
write the editing functions. 

Since MS-DOS does not currently allow multitasking, is there any way to 
perform more than one function at a time? One of the more amazing abilities of 
VC is loop functions. They give the appearance of a multitasking system by al- 
lowing a function to execute repeatedly while the computer is awaiting input 
from the keyboard. For example, the following code fragment incorporated in 
your input function will execute continuous updating of the time on the display 
screen: 


int timeloop(); 
PFI oldloop, setloop(); 


oldloop = setloop(timeloop); 


The first line declares the name of your function to display the time as 
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timeloop(). The second line uses a special typedef pF1 (Pointer to a Function). 
The driver set Loop () is supplied in the library <vcstdio.h) to simplify your pro- 
gramming. The third line actually executes timeloop() while your input func- 
tion is waiting for data from the keyboard. 

Far more complex work can be carried out. The VC demo disk has a pro- 
gram that continuously displays a text file while another form is being filled in by 
the user—and, these multiple displays are very easy to program. 


Developing User Help Screens 


It is considered almost mandatory to provide some kind of online “help system” 
for programs today, but most are seriously inadequate, plunging the user into a 
lot of information that may or may not be relevant. The best help systems are 
said to be context-sensitive, which simply means that the help you get is the help 
you need, depending upon what you are doing. However, context-sensitive help 
systems are difficult to program. Is there an easy way? 

VC provides the ability to provide help for any input statement by including 
a keyword for the help message. When the user presses the F1 function key, a 
help window opens up displaying the text you want displayed. Pressing the F1 
key again removes the help window. This is provided in the following example: 


xatget (6,0,name,"99/99/99" NULL, 
"Enter date of purchase", 
"Datehelp', vc.dft, vc.dft); 


Notice that the keyword "Datehe|p" has been added to the example that we 
previously used. Simple, isn’t it? Of course, the text for the help screen has to 
come from somewhere, and this is where VC is really helpful to you. 

First, you create a help file with any word processor. The file uses the fol- 
lowing format: - 
QaDATEHELP 
Enter the date that the purchase actually took place. 
The date should be entered in the month, day, and year 
format. Thus January 12, 1988, would be entered as 
01/12/88. You do not need to type in the slashes as 
they will be supplied by the program. 

@ONEXTHELP 


@ODATEHELP and @aNEXTHELP are arbitrary keywords which you assign. They 
are used to index the data entry field to the help message file. The aa is used to 
indicate the presence of a keyword. All the help messages are stored in one file, 
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and since the file is independent from your program, you can change the help 
messages without changing your program. This is a great advantage, since the 
messages often need clarification later. 

Next, VC provides a utility program called HELPGEN.EXE to build an index to 
the help file. When you change the text in your help file you just run HELPGEN 
again and an updated index is created. 

Finally, VC lets you provide default help messages, so that the user always 
gets a message when the F1 key is pressed. The default messages can be changed 
throughout your program. 


Creating Windows the Easy Way 


Multiple windows on the screen seem to be the user's delight and the program- 
mer’s horror—the amount of coding can be overwhelming. Witness the years of 
development of Microsoft Windows by teams of skilled programmers. Once 
again, VC provides a simple solution to this problem, by allowing you to open up 
to twelve windows on the screen at the same time. The windows can be placed 
wherever you wish, thus allowing overlapping windows. The following code 
opens a window: 


int wint; 

wint = wopen(3,10,18,34,'"'First Window'); 
wine = wopen(10,5,12,65),''Second Window''); 
win3 = wopen(23,1,24,79) ,""Command Window''); 


This indicates that the window we have optionally called win1 will be a rec- 
tangle beginning at row 3, column 10 and ending at row 18, column 34. The text 
"First Window" will be displayed as a title in the window's border. Using exactly 
the same format, we can now continue to open another eleven windows if we 
wish. 

Everything in VC works exactly the same, with or without windows. The 
only difference is that all data is written to or taken from the current window. 
The last window opened is current by default. You can also make a window 
opened earlier current with the following command: 


ret = wselect(winl); 
The ret is a variable used to capture the return code from the wselect () func- 
tion to test for correct operation. You can close a window and include error- 


checking by using this statement: 


if Cret=wclose(wint)) == -1) 
atsay(0,0,''That window is not open.'); 
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There are many other options for windows available. You can set the attri- 
butes for each window, hide or unhide windows, and have a virtual window, one 
that is actually larger than the physical size displayed. You can scroll horizontally 
or vertically to display the hidden data just as you can scroll using Lotus 1-2-3. 
You can also write to hidden windows, and when they are redisplayed, some- 
thing new will appear to the user. This is a useful trick for presenting relevant 
information without cluttering up the screen. 

VC comes with the complete source code, written in C, for all the libraries. 
This allows you to customize the functions or move them to other computer 
systems by recompiling the code. It is also furnished with a set of demonstration 
programs. They should be studied carefully, since they can be used as templates 
for building your own applications. The most interesting example is a menu sys- 
tem which uses pull-down windows like the Apple Macintosh or Microsoft Win- 
dows. The current version of VC does not provide mouse support or scroll bars, 
however. Thus, it is a simpler product with the virtue of running quickly on any 
PC and being simple to program. VC is a stunning example of clever program- 
ming, and can be used to speed up your program development time. 


Key File Access Systems 


Once you enter data into a computer system, you want to store it on a disk file 
and be able to retrieve it quickly. Most operating systems provide a variety of 
ways to access disk files. Early model computers, including PCs, provided only 
limited facilities. The four types of file access available today are sequential files, 
random files, keyed-index files and database files. Sequential files just read or 
write starting at the beginning of the file and continue until they reach the end. 
They are used today for copying entire files or for making backups of files. The 
standard DOS copY command uses this technique. 

Random files allow you to select a record from within a file based upon the 
physical record number. For most business applications, this approach is inade- 
quate. A later development, hashing, allows identifiers such as customer name 
or number, date, or invoice number to be converted into a record number, but 
this approach has its own problems in efficiently using disk space and handling 
duplicate identifiers. 

During the 1960s, the index sequential file was invented and incorporated 
into most operating systems. Using this technique, a list is created of the identi- 
fier and the corresponding physical record number. Various tricks are used to 
speed to the list processing to locate and obtain the desired record more quickly. 

In the early 1970s, computer scientists produced a new technique called 
the B + tree. This provides for very efficient records searching. A version of B + 
tree-indexing is available for most computers today (called VSAM on large IBM 
computers). All database management systems make use of B + trees internally, 
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but you don’t need to purchase a $700 package to use these techniques. You can 
purchase file access libraries to incorporate the B+ record indexing within 
your own programs. 


Using a B+ Tree Library for Your Own Programs 


We have selected C-INDEX + from Trio Systems as our example of a file access 
library. C-INDEX will allow you to add powerful indexing capabilities to your 
programs with a minimum of extra work. It offers the following features: 


variable length keys and data 

storage using multiple keys 

data and keys in the same file 

advanced B + tree implementation 
multiuser capabilities with record-locking 
full source code provided in C 


VVVY¥V VV 


no royalties on developed applications 


Let's look at each of these features and find out what they really mean. 
Many file access programs will accept only fixed length fields. This means wast- 
ing disk space. C-INDEX will automatically compress the data, wasting no space. 
If a field is left blank by the user, it takes up no disk space at all. You can define up 
to 20 key fields for each record in the standard version. 

Most file access systems require a separate DOS file for each indexed field. 
C-INDEX is completely flexible in this regard. It lets you store all the indexes and 
the data together in one MS-DOS file, if you choose, making it much easier for 
you to back up data files and reducing the disk space overhead that occurs with 
each separate MS-DOS file. On the other hand, if you really want to keep your 
index files separate, you can do so. 

C-INDEX uses advanced B + tree-indexing. This is a Third Generation prod- 
uct which has been tested on many types of computers. It has also been run 
under UNIX should you ever want to move your program up to the UNIX operat- 
ing system. The user manual even mentions use on the CRAY supercomputer, 
using UNIX. 

Functions are provided for use with multiuser systems and local area net- 
works. While this does require some changes to individual programs, these 
changes appear to be minimal. Here, however, the most important feature is re- 
cord-locking. Many other multiuse systems require the user to lock everyone 
else out of the whole file while adding or deleting records. With C-INDEX, this 
severe limitation is overcome by locking only the individual record being 
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changed. Thus, other users can continue their work on other records in the 
same file without interference. 

Finally, the full source code is provided in C, with instructions for recompil- 
ing and testing the libraries under other compilers. This means the library (and 
your programs) should not become obsolete as new products come along. No 
royalties are required, so if you plan to sell your programs, this is an important 
consideration. 


Let’s See How It Actually Works 


C-INDEX provides seven basic functions to allow you to create, open, update, 
and close files. Let's use a simple example where the data is stored in the follow- 
ing structure: 


/* structure for phonelist and notes */ 
struct nap { 

char lLastname(l10]; 

char firstname[20); 

char phone[20]; 

char notes(240]; 
+ naprec; 


The structure name napis an arbitrary name standing for name and phone. 
naprec is the name of the record using this structure. Now we need to tell C- 
INDEX how to use each of these fields. This is done by creating a “datalist,’ de- 
scribing the type of data and indicating whether it is a key field. The simplest 
way to do this is by initializing the structure with the following code: 


FIELD naplist(] = { 
STRING, STRING, DUPKEY, 10, 1, naprec.lastname, 
STRING, STRING, NONKEY, 20, O, naprec. firstname, 
STRING, STRING, NONKEY, 20, 0, naprec.phone, 
STRING, STRING, NONKEY, 240, 0, naprec.notes, 

LASTFIELD 

3 


The first line includes STRING twice since both the key and the data are of 
the type string. DUPKEY indicates the field is a key field to be indexed and that 
duplicates are allowed. (After all, some people do have the same last name.) The 
field has a maximum length of 10 characters, and the key is kept in index 1. For 
example, we could have one index based on last name and another based on first 
name and last name. In that case, the format would be: 
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STRING, STRING, DUPKEY, 30, 2, naprec.lastname, naprec. firstname 


This is a function most databases don’t provide. 

Finally, we indicate the variable naprec. Lastname to store the data. The next 
three lines are similar except that they are not key fields, hence, the NONKEY label 
with an index number of zero. 

Does it seem to you that each record will be 294 bytes long? This would 
take a lot of disk storage, most of which might be unused. However, remember 
that C-INDEX only stores the data actually input. We have a system using true 
variable-length records and a record might be only 30 bytes long. That’s why we 
have allowed such a large size for notes. 

LASTFIELO lets the compiler know the record definition is complete. Note, 
we said the compiler. Since we have initialized an array of pointers, this defini- 
tion is only performed at compile time—it is not repeated each time the object 
program is run. 


Using the “Magic 7” Functions 
Let's begin by creating the DOS files: 
ret = dcreate(&napfile, "nap.dat", workbuf, 294); 

ret is a variable for the return code. Each function always returns a code 
telling us that everything went okay or an error occurred. There is an extensive 
list of error codes to tell us what went wrong. For the function dcreate(), we 
first pass a pointer to the definition &napfilte, then the DOS filename nap.dat, 
the buffer name, and finally the buffer size (294 since it has to be large enough 
to hold the longest possible record). 

Now we want to open the file for use. The following code does the trick. You 
can see that it is exactly the same except for the name of the function: 
char workbuf[294); 
ret = dopen(&énapfile, "nap.dat," workbuf, 294); 

Closing a file is even easier: 


ret = dclose(&napfile); 


Of course, what we really want to do next is add some records to the file. The 
following little function will add records: 


addrec(); /* add a record to the file */ 
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{ 
int ret; /* return code for possible errors */ 
getdata(naplist); /* your function to get data */ 
ret = dadd(&napfile, naplist); 
if (ret != 0) printf("Error - Record Not Added.); 
} 


Your own function getdata() puts the data into the structure called 
naplist. You could (and probably should) use VC data entry functions to create 
your input function. The function dadd() then puts it into the file, providing au- 
tomatic indexing of the last name. Note that we also check the return code and 
display an error message if an error occurs. 

Now that we have a file of useful information, we are ready to find a record. 
The function dfind() does just that: 


ret = dfind(&napfile, 1, "SMITH", STRING, EQUAL); 


Once again, &napfi leis the pointer to the file, and 1 is the index number we 
are using. "SMITH" is the last name we are looking for and we want to find a re- 
cord EQUAL to that name. We also could have specified any of these choices: 


EQUAL (find only equal matches to the key) 
GREATEO (find anything equal or greater) 
GREAT (find anything greater than) 

LESS (find anything less than) 

LESSEOQ (find anything less than the key) 


Since we have this much flexibility, the user does not need to know how to 
spell the name exactly. We can write the program, using GREATEQ, so if only the 
first letter was entered, the program will page through the file. To do this, we 
use another command that will let us get the next record: 


ret = desq(&napfile, 1, NEXT); 
This function lets us move through the file sequentially. Thus, we can find 
the next record from wherever we happen to be. We can also look for the previ- 


ous record, first record, or last record, instead of the next record. Now that we 
have found the record that we were looking for, we read it into the structure: 


ret = dread(&napfile, naplist); 


Deleting a record is done with ddelete(), as you probably have guessed by 
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now. You must first use dfind() to find the record, and then ddelete() to delete 
it. "LOSEIT' is the keyword value in the record that we will delete: 


/* first find the name to delete */ 
ret = dfind(&napfile, 1, "LOSEIT' STRING, EQUAL); 


if (ret == 0) 
ret = ddelete(&napfile, naplist); 
if (ret == Q) 


fprint("'Record has been deleted.''); 


One final function allows us to update an existing record: dupdate(). To 
update the record for "JONES", we could use the following code: 


/* first find the record in the file */ 

ret = dfind(&napfile, 1, "JONES" STRING, EQUAL); 

if Cret == OK) 

ret = dread(&napfile, naplist); 

if (ret == OK) 

{ 
displayrec(naplist); /*x display old data */ 
getdate(naplist); /* get new data */ 
ret = dupdate(&napfile, naplist); 
if (ret == OK) 

printf("Update Successful'’); 


Note that we always check the return code to make sure that the operation 
was successful. We now have a complete set of seven functions for handling 
keyed files. The syntax is uniform and usage is consistent. Of course, we have not 
covered the many advanced features of C-INDEX. The 154-page user manual pro- 
vides much additional information, but you have already learned the fundamen- 
tals for using the system. 

The concepts of using keyed files is very important for most computer ap- 
plications today. I hope the example given above has shown how easily they can 
be implemented using good systems software. 


Summary 
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Effective programming today consists of using a consistent set of well-matched 
tools. The tools selected for this tutorial were very carefully evaluated. They are 
all well-designed, well-documented, and continually updated. They all work with 
the Microsoft C compiler and recent versions of MS-DOS. While there are other 
products on the market, you should examine any tools carefully before making a 
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decision that will commit you to using them for a major project. Figure 4-3 sum- 
marizes a possible integrated programming environment. 


CONFIG.SYS 


Setting up 
environment 


AUTOEXEC.BAT 


Menu Program 


Executing 
programs 


Editor 
Vitamin C 
and 
C Compiler C-INDEX 
include 
fites Developing new 


programs using 
Vitamin C and C-INDEX 


Vitamin C 
. and 
MS-DOS C-INDEX 
Object 


libraries 


Fig. 4-3. An integrated development environment. 
If you are an individual programmer, your work will become more fun and cre- 
ative by following these guidelines. If you are working on program development 
for your company or for commercial sale, the approach described herein can 
save your firm hundreds of hours of development time. 


Programs 


RETRIEVE is available from IBM Personally Developed Software on their Utilities 
I disk. The price is $19.95; it can be ordered by calling 800/426-7279. 
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EXTENDED BATCH LANGUAGE is available as shareware from BBSs and user 
groups. It may be registered by calling Seaware Corporation in Delray Beach, 
Florida at 305/392-2046. The price is $69.95. They will send you the latest pro- 
gram version, a 366-page printed manual, and a password for their user BBS. 


VITAMIN C is published by Creative Programming Consultants, Inc.; Box 112097; 
Carrollton, TX 75011-2097. The price is $149.95; you can order by phone by call- 
ing 214/245-6090. 


C-INDEX is available from Trio Systems; 2210 Wilshire Blvd.; Suite 289; Santa 
Monica, CA 90403. The price is $395.00; their telephone number is 203/394- 
0796. 
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Techniques 


Michael Goldman 


Ir you have been writing assembly language code, you know that what most 
often trips you up is the detailed repetitive work, having to recode every BIOS 
call every time you want to do some simple task like reading the keyboard. 
Microsoft's MASM, version 5.0, like many good assemblers, offers many power- 
ful features to make coding assembly language as easy and error-free as a good 
higher-level language. We will look at the following MASM features which can 
help you as a programmer: 


> records (setting up and manipulating bit-oriented data using meaningful 
names) 


[> structures (creating relationships between pieces of data similar to those 
found in C or Pascal) 


> include files (saving time and typing, improving program organization) 


> macros (creating flexible, powerful “super instructions”) 


Records 


Records are very convenient templates for setting up bit-oriented data struc- 
tures. They save time, and by automating the process, help us avoid errors in 
setting our data bits. For example, in a byte used for setting up the line control 
register for the Asynchronous Communications Element (ACE) (i.e., COM1 or 
COM2) bits 0 & 1 set the word length, bit 2 the number of stop bits, bits 3 
through 5 the parity, bit 6 the break conditions, and bit 7 is the Data Latch Ac- 
cess Bit. To work with all these parameters in one byte, we can define a record 
called LineCtr]Bits as follows: 
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LineCtrlBits RECORD DOLAB:1, BREAK:1, PARITY:3, STOP:1, LEN:2 


LineCtrlBitsis the name of the record, which represents one byte (8 bits). 
DLAB, BREAK, and so on represent fields in the record, and are followed by the 
number of bits for each field. Note that this definition merely gives names to the 
bits in a byte, it doesn’t create a byte with those bits set or cleared. Just as MyWord 
dw 1234 creates a word with the value 1234, so we create a record for particular 
combinations of bit settings with the following statements in the DATA segment 
of the program: 


LerOnEven27 LineCtrlBits<DLABon, BreakOff,EvenParity,stop2, Length7> 
LerOffOdd18 LineCtrlBits<DLABoff, BreakOff ,OddParity,stop1, Length8> 


Note that the name of the specific record (such as LcrOnEvn27) is followed by the 
name of the record definition used (LineCtrlBits in this case) and then the 
names of bit values. 

In the equates section of our program we have defined: 


DLABof f equ OB ; Data Latch Access Bit off 
DLABon equ 1B ; Data Latch Access Bit on 
BreakOff equ OB 3; set break is disabled 
BreakOn equ 18 ; xmit data line forced to space 

; Clogical 0) as long as bit is one 
NoParity equ 000B ; bit setting for parity off 
OddParity equ 0018 ; bit setting for odd parity 
EvenParity equ 0118 ; bit setting for even parity 
MarkParity equ 1018 ; bit setting for mark parity 
SpaceParity equ 1118 ; bit setting for space parity 
stop1 equ 0B 3 1 stop bit 
stop2 equ 18 ; 2 stop bits if word 6, 7, or 8 bits 
Length5 equ 008 3; 5-bit character Length 
Length6 equ 018 3; 6-bit character length 
lLength7 equ 10B 3; ?-bit character Length 
Length8 equ 118 ; 8-bit character length 


We can now write an instruction such as MOV AL, LcrOf f0dd18in our program as if 
we had defined a byte as follows: 


LerOf f0dd18 db 00001011b ; ACE bit settings 


Note that we cannot write MOV AL,NoParity since NoParity is not a byte but 
rather just the value of an equate. Likewise, if we write MOV AL, BREAK, what we 
find in ALis not a bit moved into bit 6 but the number 6, which is the position of 
BREAK in the record. 
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Manipulating Bit Fields 


So far, it may appear that records are just a convenient way to define bit-oriented 
data, but there is more we can do. The TEST instruction allows us to do with bits 
what CMP (COMPARE) does with bytes and words. The Intel logical instructions 
AND, OR, XOR, and the MASM directive NOT allow us to manipulate the bit fields. 
The NOT directive changes 1s to Os, and Os to 1s. 

Use the bit fields in the record LineCtrl8its as above, so we can use the 
MASM directive MASK to define what are called (naturally enough) masks. The 
MASK operator tells MASM to create a binary constant with a bit set to 1 for the bit 
positions defined in the record by that record field and a zero for all the other 
bit positions. For example: 


DLABmask = MASK DLAB s = 100000008 
BREAKmask = MASK BREAK ; = 010000008 
PARI TYmask = MASK PARITY ; = 001110008 
BIT2 = MASK STOP ; = 000001008 
LENmask = MASK LEN : = 000000118 


We've called the mask defined for the stop bit BIT2 to show there's no restriction 
on what you name the mask. Now we wish to change the parity setting in 
LerOffNo18 from off to even, i.e., from 000 to 011. We'll use the MASK operator to 
help, for instance, NOT PARITYmask = 11000111b (NOT works only at assembly time, 
not run time). 


and LcrOffNo18,NOT PARITYmask ; LecrOffNo18 = O00000011b 

mov al,LcrOnEven27 ; al = 00011110b, even parity setting, etc. 
and al, PARITYmask s al = 00011000b, all but parity bits cleared 
or LcerOffNo18,al s LerOffNo18 = 00011011b, even parity setting 


The use of symbolic constants helps control bits of records in MASM. In the 
first line of the example, LcrOffNo18is a data record for the Line Control Register 
on the serial port, and is followed by the MASM NoTinstruction. PARITYmaskis the 
mask created with MASM’s MASK directive. LcrOnEven27 means Line Control Reg- 
ister, with Break On, Even parity, 2 stop bits, 7 bits long. 

A reminder about AND, OR, and NOT operations: these are called “logical’ 
operations because they obey the rules of Boolean logic. They work as follows: 


landi=1, landO=0, Oand1=0, Oand0O=0 

lorl=1 lor oO = 1, Oorl1 = 1, Oor0O = 0 

not 1 = QO, notO = 1 

So, the first instruction in the example ANDs 11000111b (NOT PARITYmask) 
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with 00000011b (Lcr0fNo18) to produce 00000011b. The purpose of this is to clear 
out the parity bit settings so that we can put new settings in there with the or 
instruction later. The next instruction loads at with 00011110b (LcrOnEven27). We 
then AND the 00011110bin al with 00111000b (PARITYmask) to obtain 00011000b. 
The PARITYmask masks (zeros) out all the bits in al except the parity bits so that 
alis left with only the bit setting for even parity. Now we OR LcrOffNo18 with at 
which will put the bit settings we want into the parity bit positions. Note that had 
we not done the and al,PARITYmask , there might have been some bits from the 
previous setting which would come through the oR operation. 

Thus, we have succeeded in changing the 3 parity bits without affecting the 
other bits. Just as we might use a CMP instruction to see if two bytes are the same, 
so we can use the TEST instruction to see if any of the parity bits are set, for 
example: 


test ax, PARITYmask ; parity bits set in ax ? 
jz BlankParity ; if zero flag, blank parity field 


Records can be created and used on preexisting data. So, for example, we could 
have defined the byte 


anybyte db 01001111b ; no thought of records here 


and then at some later time in our programming define the record LineCtrlBits 
as above. We could also refer in the same program to the same word with a dif- 
ferent record definition such as 


Simple RECORD Begin:2,Middle:3,End:3 


and do the same bit manipulations as previously with the three parity bits, refer- 
ring to them as Middle instead of Parity. The point is that, at any time, we can 
create ways of referring to data in whatever way is appropriate in the context. 
The record is a template to fit over data. Figure 5-1 shows a typical use of re- 
cords. DLAB indicates the Data Latch Access Bit, and LEN refers to character 
length. BREAK, PARITY, and SsToP bits are also shown. 


Structures 
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Structures are the next level up from records in imposing order on our data. 
They are assembler directives that enable you to build complex data formats 
composed of bytes, words, etc., in ways that make them much more meaningful 
and accessible to you. They are very similar to C structures and Pascal records. 
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BREAK PARITY STOP LEN 


Fig. 5-1. Records as templates. 


They differ in that, in MASM, indexing is harder and nesting is not allowed. As 
an example, suppose you are making a membership list in which every member 
is listed with name, address, and phone number. Here’s how you can create a 
structure for this entity: 


Member STRUC 
LastName DB20 DUP (7) 
MidInit DB? 
FirstName DB12 DUP (7) 
Street DB12 DUP (7?) 
City DB 'San Francisco’ 
StateAbbr DW? 
PhoneNumb DB'415' 7 DUP (7) 
Member ENDS 


20 characters 
1 character 

12 characters 
12 characters 
13 characters 
2 characters 
10 characters 


ee. =e =e 


~=s te Be MO 


City, PhoneNumb, etc., are called field names” for the Member structure (see Figure 
5-2). You can now allocate space for the officers and members of your organiza- 
tion with 


President Member <,,,,,'CA',> 
VicePresident Member <,,,,,‘CA',> 
Treasurer Member <,,,,,'CA',> 
MembrList Member 100 DUP (<,,,,,'CA',>) 


which reserves space for 103 members. At 70 bytes/member, this is 7210 bytes for 
our membership list. Each member's city is initialized by default to San Francisco 
in the structure definition, and each state is initialized to CA in the structure 
declaration. The places where we have commas are blank field names that you 
can fill in with data later, at run time, reading in from a keyboard or disk, etc. 
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Required MASM 
Space Field Names 
20 chars LastName 

1 char Midinit 
12 chars FirstName 

2 chars || StateAbbr 
10 chars 4/5 PhoneNumb 


Fig. 5-2. Structure layout. 


This is a good time to point out that in MASM, the following are equivalent 
ways to refer to the address in register di plus 10: 


C10) dil 
Cdi + 10) 
CdiJ].10 

CdijJ + 10 


Therefore, since the structure is really just giving mnemonics to displacements, 
you can now refer to the membership list by the field names, just as you might in 
C or Pascal. For example: 

cmp Treasurer.FirstName, 'A' 

is equivalent to 

cmp (Treasurer + 21],'A' 

which compares the first byte of the FirstName field of the Treasurer's name. 


For example, if we wish to scan the entire list of members for the first member 
with last name beginning with A we would code 


mov di,MemberList ; get address of List 
mov cx,100 ; length of list for looping 
mov bx, 70 ; length of structure 

CmpLup: cmp Cdi].FirstName,'A' ; is the first letter = ‘A’ 7? 


je ExitLup , yes, search done 

add di,bx >; set pointer to next structure 

loop CmpLup 7 scan the entire List of members 
ExitLups... 
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Using Multiple Structures to Address Data 


It is possible to add to the options in addressing the data by defining another 
structure for the same data: 


NewMembr STRUC 
Name DB 33 DUP (7) 
Address DB 27 DUP (7) 
Phone DB 10 DUP (7?) 
NewMembr ENDS 


Without reentering the old data, we can now refer to it by the NewMembr structure 
names as well as the Member structure names. We could write this comparison 
loop: 


CmpLup: cmp Cdi]. LastName, 'A' 
je ExitLup 
add di,bx 
Loop CmpLup 
ExitLup:cmp Cdi].Phone, '4' 
jne cae 


The key to understanding structures is to realize that MASM simply replaces 
the names you give to the structure elements with numbers. Specifically, MASM 
will reference the number of bytes from the beginning of the structure. Thus, 
Cdi].FirstName is the same as [di+20]. The name you give it is for your easy use. 

One very useful feature of using structures is that you can rearrange or 
add to the structure definition at any time and the names you gave the elements 
will be automatically updated when you reassemble. For example, let's change 
the Member structure above to interchange FirstName and LastName and add the 
element Country: 


Member STRUC 


FirstName DB 12 DUP (7?) s 12 characters 
MidInit DB : 1 character 

LastName DB 20 DUP (7?) s 20 characters 
Street DB 12 DUP (7) ; 12 characters 
City DB ‘San Francisco’ ; 13 characters 
StateAbbr OW s 2 characters 

Country DB 6 DUP (7) : 6 characters 
PhoneNumb DB '415' 7 DUP (7) ; 10 characters 


Member ENDS 


To see what this does, here are the “before” and “after” equivalencies: 
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BEFORE AFTER 

Cdi].LastName = [di+0] CdiJ.LastName = [di+13] 
Cdil].MidInit = ([di+20] Cdi].MidInit = [di+12] 
CdiJ.FirstName = (di+21] Cdil.FirstName = (di+0] 


C(di).Street = (di+33] (di].Street = [{di+33] 
(di).City = [di+45] Cdi].Ccity = (di+45] 
Cdi].StateAbbr = [di+58] Cdi].StateAbbr = [di+58)] 
------ Cdi].Country = [di+60) 


CdiJ.PhoneNumb = [di+60) Cdi].PhoneNumb = [di+66] 


The nice thing about having used structure names in our code is that 
Cdij.LastName still points to the last name even though we've rearranged the 
data. So, code referring to data by structure name needn't be rewritten. Note, 
however, that if we have data in our file using the old structure definitions, we 
must realign that existing data to conform to our new structure. Rearranging 
the structure doesn’t rearrange the existing data, only the relative positions de- 
clared for it. We have to ensure that the actual data corresponds to the data 
structure declaration on our own. 


Using Structures with Existing Data 
You can also apply a structure you define to a data set that you had no hand in 


creating. For example, the first 22 bytes of the PSP that MS-DOS puts at the be- 
ginning of executable files could be accessed via the following structure: 


PSP STRUC 
INT32 DB 2 DUP (7?) ; 2 bytes 
MemSize DW (7) ; 1 word 
Reserved DB (7) : 1 byte 
DOSCall DB 5 DUP (?) ; 5 bytes 
TermVctr DW 2 DUP (7) ; 2 words 
BreakVctr DW 2 DUP (7?) 3; 2 words 
ErrorVctr DW 2 DUP (7?) : 2 words 

PSP ENDS 


The PSP can now be accessed as in the following code fragment: 


mov di,O ; PSP begins at offset zero 

push cs ; PSP segment is in cs 

pop ds ; PSP segment -> ds 

mov si, {di].MemSize ; program memory size -> extra segment 


Note that, unlike C, structure definitions cannot contain other structures. 
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Include Files 


The simplest way to avoid retyping “boilerplate” lists of equates, code, or seg- 
ment declarations is to use include files with these where you would otherwise 
put your text. You simply put your frequently used constructs in a standard DOS 
file as ASCII text and tell MASM to insert the text from that file in your proce- 
dure. To use an include file, you specify 


include myfile.xyz 


where you would otherwise have put the equates, definitions, etc. MASM brings 
in the contents of these files at assembly time and treats them as text as if you 
had typed everything in the include file in that spot in your program. Include 
files can contain other include files. Figure 5-3 illustrates the idea of bringing in 
files to insert in your source file. Use “greeking” (nonsense) text in the include 
files to represent codes. 


Source File 


Include Files 


| A EQU 1 | 
| A MACRO 


include Combo.inc 


include STANDARD.STK <QgemaEEEnee 


| stakseg 


include Stdcode.inc 


Fig. 5-3. Use of include files. 


For example, if your standard stack declaration is 


stakseg SEGMENT STACK ‘STACK 
DB 16 DUP C'STACK ) ; MAKE STACK EASY TO FIND IN DEBUG 
stakseg ENDS 
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then simply put this into a file called STANDARD.S TK or some such, and then 
inc Lude STANDARD. STK where you would normally type in your stack declaration. 
Finally, having an include file for each set of related definitions promotes modu- 
lar organization and helps make programs easier to maintain, especially when 
several programmers are involved. 


Data Macros 
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Macros are a very flexible way of having the assembler do a lot of the tedious 
work for you. Macros can be used to generate both data and actual MASM code. 
Much of their power comes from their ability to accept parameters and do con- 
ditional testing. Setting up tables, creating labels, and checking for errors can all 
be done by macros that you create to meet your needs. We'll cover code macros 
later but remember that everything used for data macros can be used for gener- 
ating code as well. Data macros are instructions to the assembler to create cer- 
tain data based on parameters we give it (see Figure 5-4). The simplest example 
of this is when we create 10 bytes of data with 


TenBytes DB 10 DUP 4 ; reserve 10 bytes with the 
; number 4 in them 


Source Code 


Reserve 10 bytes 


with the number 4 
in them 


Minrenran 


Result tn 
Memory 


Fig. 5-4. Data macros reserve space for variable names. 
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This is of limited use since it is more likely that we want a variety of num- 
bers as in an indexing set. For example, let's reserve N bytes of data with the set 
of squares of the numbers from 1 to N as follows: 


@squares MACRO N ; Define a macro with parameter N 
NUMB = 0 : Initialize the number 
REPT N ; Repeat the following N times 
NUMB = NUMB+1 ; INCREMENT INDEX 
DB NUMB * NUMB ; Define a byte with NUMB squared 
ENDM s End REPT command 
ENDM ; End Macro 


Note that we have an ENDM to match every MACRO directive. 

The REPT directive is a looping structure like “do . . . while” in higher-level 
languages. Just bear in mind that you are programming MASM to create con- 
stants. You are not programming the computer to loop at execution time. 

If we put the squares macro definition at the top of our program and then 
in our data segment, we have 


asquares 4 


MASM will assemble 4 bytes as seen in the following listing: 


94 @squares 4 

95 0004 01 2 DB NUMB * NUMB : Define a byte with NUMB squared 
96 0005 04 2 0B NUMB * NUMB”) ; Define a byte with NUMB squared 
97 0006 09 2 0B NUMB * NUMB-” ; Define a byte with NUMB squared 
98 0007 10 2 0B NUMB * NUMB”) ; Define a byte with NUMB squared 


The invocation of our macro is on line 94 of our listing. The next 4 lines 
show that byte 4 of our data segment has 1 squared = 1, byte 5 has 2 squared = 
4, etc. Note that the numbers are given in hex. The 2 before the 0B is the line 
number of the macro listed. We could, of course, have used a number other than 
4 as well. 

We need a label to use to refer to this list of squares. We don’t want to type a 
label every time we use the macro so we'll use the Substitute operator & to have 
MASM make our label for us: 


asquares MACRO N : Define a macro with parameter 
N 
Sqri1to&N Label byte Define a label 


NUMB = 0 
REPT N 
NUMB = NUMB+1 


Initialize the number 
Repeat the following N times 
Increment index 


=e me =e me 
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DB 
squared 
ENDM 
ENDM 


NUMB * NUMB 


’ 


Define a byte with NUMB 


End REPT command 
End Macro 


Now the list file shows our macro as follows: 
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94 0004 
95 0004 
96 0005 
97 0006 
98 0007 


@squares 4 
1 Sqrito4 
2 OB 
2 DB 
2 DB 
2 DB 


Label 
NUMB * NUMB 
NUMB * NUMB 
NUMB * NUMB 
NUMB * NUMB 


01 
04 
09 
10 


byte 


e 
e 
s 
° 
& 


* Define 


; Define a Label 
Define a byte with NUMB 
Define a byte with NUMB 
Define a byte with NUMB 
a byte with NUMB 


squared 
squared 
squared 
squared 


&in the macro definition told MASM to substitute the value of N used in the 
macro invocation. But still we're not satisfied. (We never are!) Having only one 
label for the list of squares will force us to use an index to access the list since 
there is only one access point. What we'd like is a label for every item. The ex- 
pression operator % will enable us to take the value of each of our numbers and 
use it as part of a label. So we rewrite our macro as the two macros below: 


asqr MACRO NAM,NUM 
SqrOf&NAM DB NUM * NU 
ENDM 
@squares MACRO N 
NUMB = 0 
REPT N 
NUMB = NUMB+1 
@sqr %NUMB,NUMB 
ENDM 
ENDM 


’ 


M 


=e. 


NAM for our label, NUM for the data 
; Define a byte with NUMB squared 
End Macro 


Define a macro with parameter N 
Initialize the number 

Repeat the following N times 
Increment index 

Create a byte of NUMB * NUMB 
End REPT command 

End Macro 


Now when we look at the listing file, we find each byte in our list of squares 
(below) has an appropriate label for our use: 


97 

98 0004 
99 0005 
100 0006 
101 0007 


@squares 4 
01 3 SqrOfi DB 
04 3 SqrOf2 DB 
09 3 SqrOf3 0B 
10 3 SqrOf4 DB 


NUMB 
NUMB 
NUMB 
NUMB 


* NUMB ; Define a byte with NUMB squared 
* NUMB ; Define a byte with NUMB squared 
* NUMB ; Define a byte with NUMB squared 
* NUMB ; Define a byte with NUMB squared 


We can create sophisticated tables in this way. If we have some formula 
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such as (N*M) /((P+Q) MOD T), we can let MASM create our table for us instead of 
doing it by hand and typing in the results. 

We could and should check for overflow by including the following in our 
macro code: 


IFE CCNUM * NUM) LE 255) 3; bigger than a byte can hold ? 
DB NUM * NUM ; ok, small enough for a byte 
ELSE 
ZOUT ERROR IN SQUARES MACRO 


“OUT sends your message to the screen at assembly time, in this case ERROR IN 
SQUARES MACRO. 

So far, we have always used parameters as individual items separated by 
commas. It is also possible to have a set of items be a single parameter to the 
macro for repetitive data creation. For example, if we want to set up a list of 
strings of messages to display, we could code a macro as follows: 


a0ptDisp MACRO OptType,Options ; OptType -> label, Options = 
List 

OptType&List db Options 

ENDM ; End Macro 


and then use it in the data segment as follows: 
@O0ptDisp LineSpeed,<'1200' ,'2400','4800'> 


LineSpeed will be substituted in the label and each string in the angle brack- 
ets will be put in a db directive, just as if we'd typed in 


LineSpeedList db ‘1200' 
db '2400' 
db '4800' 


There's much more you can do with macros to generate data but these are 
a good idea of the possibilities. The same techniques can be used to generate 
code as well as data. 


Code Macros 


Macros are a very powerful way of getting the assembler to do some program- 
ming for you. Just as you can write a BASIC program to make the computer do 
some work for you, so you can write a MACRO program to make the 
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ASSEMBLER program, MASM, do some of the most tedious aspects of pro- 
gramming for you. 

A simple example of what we mean is the following macro designed to get a 
character from the “standard input device” (usually the keyboard). 


@INCHR MACRO ; Tell MASM we're defining a macro named INCHR 
MOV AH,1 :; STANDARD INPUT WITH ECHO 
INT 21H ; DOS CALL 

ENDM s Tell MASM the macro definition is ended 


Now, instead of retyping the Mov and INTinstructions whenever we want to 
get a character from the standard input, we can use INCHR where we would oth- 
erwise have written the code: 


QINCHR ; MASM substitutes MOV AH,1 & INT 21H here 


You could do the same thing with a subroutine but making short pieces of 
code into subroutines is inefficient. The difference between a macro and a sub- 
routine is that the macro inserts the desired code right where our macro is 
placed in the source file, whereas a subroutine resides elsewhere and we have to 
jump to that location to execute the code. We use a macro instead of a subrou- 
tine for the same reason we call someone on the phone for a short conversation 
instead of going across town to visit—the time lost in going to another location 
isn't justified given the brevity of our task. Thus, code macros tend to be very 
short since they take up space every time they are used. If they get too long, they 
should be recoded as a subroutine. How long is too long? That depends on the 
overhead needed to invoke the subroutine, how often you use the function, and 
the relative value of memory versus speed for your application. Macros are 
faster since they don’t require saving registers, pushing parameters, etc., but a 
lot of repetitions of short macros can start taking up space in your object and 
executable files. Make the code a macro at first and if it seems to be getting out 
of hand, recode it as a subroutine. Later, we'll see how you can even code the 
subroutine call as a macro. 

Suppose we want to have a macro for standard input with no echo. We 
could write another macro like the one above but calling DOS for standard input 
with no echo, or we could expand our original macro by adding an argument to 
determine if we want echo or not. For example: 


@inchrif MACRO EKOFLAG ; define macro INCHRIF with argument EKOFLAG 
IFIDN <EKOFLAG>, <EKO> ; if the argument EKOFLAG is IDENTICAL to 
the 3 letters EKO, assemble the next line 
DOS function - standard input with echo 

if the argument EKOFLAG is NOT IDENTICAL to 
the 3 letters EKO, assemble the next line 


mov ah,1 
ELSE 


=e. ae =e =e 
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mov ah,8 ; DOS function - standard input with no echo 
; end condition testing 

int 21th ; dos call 

ENOM ; Tell MASM the macro definition is ended 


ENDIF 


In this case, MASM looks at the argument EKOFLAG to determine whether to in- 
sert mov ah,1 or mov ah,8. It would be used as shown below: 


@inchrif EKO ; MASM substitutes MOV AH,1 & INT 21H here 
: ; because the argument is identical to EKO 


@inchrif NOEKO ; MASM substitutes MOV AH,8 & INT 21H here 
- ; because the argument is NOT identical to 
z ; EKO 


Note that instead of NOEKO in the example, we could have used PHUBAH or 
anything else since the important thing is that the argument not be Eko. If it 
were, it would leave open the possibility we would forget our odd spelling and 
mistakenly write dinchrif ECHO. This would give us no echo because we wrote 
ECHO instead of EKO. We can eliminate this error possibility by limiting ourselves 
to either EKO or NOEKO and by providing error-checking as follows: 


@inchrif MACRO EKOFLAG ; define macro INCHRIF with argument EKOFLAG 


IFIDN <EKOFLAG>,<EKO> ; if EKOFLAG = EKO, assemble the next Line 
mov ah,1 ; standard input with echo 
ELSE . otherwise... 


IFION <EKOFLAG>,<NOEKO> ; if EKOFLAG = NOEKO, assemble the next Line 


mov ah,8 3; standard input with no echo 

ELSE ; if the argument doesn't match either then 
-ERR 3; generate an assembly error 

ENDIF ; end condition testing 
int 2th 3; dos call 

ENDM ; Tell MASM the macro definition is ended 


Nested Macros 


The macros we have been defining use the DOS function to get a character from 
the standard input by waiting for input. But we don’t want to wait forever. In- 
stead, we may wish to check if input is there first, and if not, continue on. DOS 
Function OBh will check if a key has been struck, returning AL = OFF (hex) if a 
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character is available and AL = OOif a character is not available. We can write a 
macro chkchr and call it from our macro inchrif as follows: 


@chkchr MACRO ; define macro CHKCHR 
mov ah,OBH ; check standard input 
int 2th : dos call 
ENDM s Tell MASM the macro definition is ended 


@inchrif MACRO WAITFLAG,EKOFLAG ; 2 arguments: WAITFLAG, & EKOFLAG 
LOCAL bye ; define a dummy address 
IFNB <WAITFLAG> : if the field for WAITFLAG is not 
s blank, assemble the following 


achkehr ; see if a character is waiting 
cmp al,0 ; al = 0 => no character waiting 
je bye : if no character, continue on 
ENDIF ; end condition testing 
IFIDN <EKOFLAG>, <EKO> 3; 1f EKOFLAG = EKO, assemble the next Line 
mov ah,1 s standard input with echo 
ELSE ; otherwise... 
IFIDN <EKOFLAG>,<NOEKO> ; if EKOFLAG = NOEKO, assemble next line 
mov ah,8 ; standard input with no echo 
ELSE ; if the argument doesn't match either then.. 
ERR $s «e-generate an assembly error 
ENDIF ; end condition testing 
int 21h 3; dos call 
bye: 
ENDM ; Tell MASM the macro definition is ended 


This newest version of inchrif has several features worthy of discussion. 
The LOCAL directive tells MASM that the label bye is a “dummy” label which 
MASM is to replace with a different one every time the macro is invoked within a 
program. This is to avoid having the same label used twice in one program, gen- 
erating an assembly error. MASM will assemble the macro using ??0000 the first 
time in a module, ??0001 the second time, etc., through ??FFFF (hex) should you 
care to invoke the macro 65,536 times in one program. Note that the LOCAL direc- 
tive must be the very first thing after the MACRO directive—not even comments 
can be placed before it! 

The IFNB WAITFLAG tells MASM to assemble the 3 lines following only if the 
argument WAITFLAGis not blank. Otherwise, the code is not included and the first 
line assembled will be one of the lines governed by IFIDN. This gives us the option 
of generating either code that will wait for input forever or code that will just 
check the keys and go on if nothing's there. The IFN6 checks for existence of 
WAITFLAG, not for spelling, so we could invoke the macro by any of the following: 
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@inchrif WAIT,EKO 
@inchrif WAITE,EKO 
@inchrif NoWate,EKO 
@inchrif FOOBAH,EKO 


and still generate code that does not wait for input. Note also that we have nested 
our macros, one macro invoking another. 


More Macro Features 


Instead of using only the WAITFLAG to determine whether to assemble the code 
for waiting, we might also make it a global option that we can choose at assembly 
time. For example, we might like it to wait for a key if we’re debugging or if the 
WAITFLAG is set, but not wait otherwise. While we're extending this macro, we'll 
throw in some other new stuff. The new macro definition is 


@inchrif MACRO WAITFLAG, EKOFLAG 
LOCAL bye ; define a dummy address 
; Macro to get a character from the standard input 
; 2 arguments: WAITFLAG, & EKOFLAG determine whether to wait for a 
; character, and whether to echo the input 


; 
; 
; 
x 


= 0 ; x will be our indicator 
IFNDEF DEBUG ; if the parameter DEBUG is not defined, 
x = 1 ; flag = 1 
ENDIF ; end condition testing 
IFNB <WAITFLAG> : if the field for WAITFLAG is not blank 
x = 2 3; flag = 2 
ENDIF ; end condition testing 
IF (x eq 1) or (x eq 2) ; if either DEBUG is not defined, or 
; WAITFLAG is not blank 
achkchr ; see if a character is waiting 
cmp al,O ; al = 0 => no character waiting 
je bye s if no character, continue on 
ENDIF 3; end condition testing 


IFIDN <EKOFLAG> , <EKO> ; if EKOFLAG = EKO, assemble the next Line 
mov ah,1 ; standard input with echo 
ELSE . otherwise... 
IFION <EKOFLAG>,<NOEKO> ; if EKOFLAG = NOEKO, assemble next Line 
mov ah,8 ; Standard input with no echo 
; if the argument doesn't match either then 
»ERR ; «--generate an assembly error 
“OUT ; Error in INCHRIF MACRO - EKOFLAG not found 


ELSE 
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ENDIF s; end condition testing 
ENDIF s end condition testing 
int 21th 3; dos call 
bye: 
. CREF 3 restore cross-referencing 
ENDM 3 Tell MASM the macro definition is ended 


Now at assembly time we can use the /d option to define DBUG: 
MASM myprgm,,,; /dDBUG 


and all the invocations of inchrif will generate code to wait for input. 

We have used a flag (with = instead of equ since we redefine it in the next 
two IF statements) to determine whether or not we wait for a character. Instead 
of (x eq1) or (x eq 2), we could have coded x gt Oor x ne Osince any value other 
than our initial value of 0 is valid. 

Note that we also added a few new directives. The ;; tells MASM the com- 
ment should not be in the assembly listing. The .xXCREF saves assembly time and 
cross-reference listing space by telling MASM not to clutter up our cross-refer- 
ence listing with the names used only in the macro. .CREF restores cross-refer- 
encing or it would be off for the rest of the listing. We have also added the “ouT 
directive which will write to the screen the error message given. 

Though there's plenty more we could do to it, this has become a pretty fear- 
some macro, so we'll leave it here and let you figure out all the complications left 
to add. 

As promised earlier, we'll now show you how a generic subroutine call can 
be coded as a macro. The task is to push some parameters on the stack and call 
the subroutine. Pretty simple, except that we want a variable number of parame- 
ters, and we want to allow for byte and word parameters. The word parameters 
are easily handled, we simply pushthem. But byte variables have to be converted 
to words first. The macro below takes care of this problem: 


@FcenCall MACRO Fnctn,ParmList subroutine, & List of parameters 


e 
IRP N,<ParmList> : indefinite repeat (see below) 
IF (C. TYPE N) NE 22H) s is N data-related and defined ? 
push N s if so, done 
ELSE 
IF (CTYPE N) EQ 2) ; if 2-byte parameter 
push N 5 push it 
ELSE 
IF (CTYPE N) EQ 1) ; if 1-byte parameter 
mov ah,0O ; clear upper byte of ax 
mov al,N ¢ parameter now a word... 
push ax 3 «+.SO we can push it 
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ELSE 
-ERR 
ENDIF 
ENDIF 
ENDIF 
call Fnctn 
ENDM ; Tell MASM the IRP is ended 
ENDM ; Tell MASM the macro definition is ended 


We have used the TYPE operator which will return a 1 if the parameter is a 
byte, and a 2 if the parameter is a word. We also introduced the . TYPE operator 
to make it work with registers. Don’t confuse this with the TYPE operator. There's 
a “” as the first character of this new operator. Using .TYP€ allows the macro to 
handle a register such as BX as well as a data word or byte. . TYPE x returns a byte 
with the bits set according to the following scheme: 


Bit O = 1if x is code related, 0 otherwise 
Bit 1 = 1/if x is data related, 0 otherwise 
Bit 5 = 1if x is defined, 0 otherwise 

Bit 7 = 1if x is external, 0 local or public 


All other bits are zero. 

For example, if x is data-related, defined, and local, .TYPE x returns 
00100010b (22 hex) (bit 1 is set and bit 5 is set). Since we want to allow the use of 
registers (which are code related) as parameters, we will use the . TYPE operator 
to tell us if we have data-related parameters. 

We've introduced IRP, the indefinite repeat macro directive. This tells 
MASM to repeat the instructions once for each element of the list enclosed by <>, 
substituting each element of the list for the dummy variable. For example: 


IRP y,<1,2,3> 
db y 
ENDM 


will generate 


db 4 
db 
db 3 
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The nice thing about IRP for our purposes is that we don’t have to specify in 
advance how many parameters we wish to send to the subroutine until we call it. 
We could call one routine with 3 parameters and another routine with 2 param- 
eters. For example: 


aFcnCall Fcen1,<word1,word2,byte3> 
@FcnCall Fen2,<word1,byte3> 


and so on with virtually unlimited numbers of parameters for any subroutine 
call we wish. 


Structures As Subroutine Parameters 


While this FcnCall macro has been very instructive as a way of demonstrating 
MASM operators and directives, the best way to pass parameters to a subroutine 
is via a structure address. As an example, let's pass to our subroutine the data in 
one of the elements of our member list defined in our discussion of structures. 
Addresses are always the segment and offset. If we use a label of our data struc- 
ture, such as Treasurer, then we can code 


push offset Treasurer 
push segment Treasurer 
call Fen1 


If we have a label of a list, such as MembrList in the example on structures, and an 
index displacement from that label, we use [MembrList + di] instead of Treas- 
urer. 

If we want to send only one element of the structure, such as the phone 
number, we use [MembrList + di] .PhoneNumb where we had Treasurer originally. 
So now the macro to make subroutine calls and pass parameters is simple 
enough that I can leave you with those immortal words, “It is left as an exercise 
for the reader”! 


Interrupt Tips 
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If you have done much assembly language programming on the IBM PC, you 
have probably used software interrupts like INT 21 to make a DOS call, or INT 13 
to make one of many BIOS calls. There are also hardware interrupts that can be 
of use when using the communications ports (COM 1 or COM2), the keyboard, or 
the timer. Unfortunately, the proper techniques for writing an interrupt service 
routine (ISR) can be tricky. Let’s look at the basic considerations. 
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ISR, the ISR itself, and one to remove the ISR. 


There are three routines needed to handle interrupts: one to install the 


The ISR install routine simply uses DOS Function 35h to get the address of 


the current ISR for the interrupt in question, and DOS Function 25h to set the 
current ISR address. The following routine installs ISR CHKINT to respond to in- 


terrupt 4: 

data segment PARA public ‘data’ ;define segment 
OldVectorAdr label dword ; double word for lds instruction 
OldVectoroff dw 0 ; offset of old vector 
OldVectorSeg dw 0 ; segment of old vector 


NewVectorAdr Label 
NewVectoroff dw 


NewVectorSeg dw 

data ends 

mov ax, 350ch 

int 21h 

lea si,OldVectoroff 
mov CsiJ,bx 

mov Csit+2],es 

push ds 

lds dx,NewVectorAdr 
mov ax,250ch 

int 2th 

pop ds 

in al, IMR 

and al ,OEFh 

out IMR, al 

cli 

mov al,2Oh 

out 20h,al 


dword ; double word for lds instruction 
offset CHKINT ; offset of ISR = New vector 
seg CHKINT ; segment of New vector 


=e Se Te Ms Be Be Ms Be BH BH BO VS we e 


=e =e =e =e =e 


=e =e me =e 


=e 


ah=35h = DOS "get current int vector" 

int Och (= 4 * interrupt number) -> al 

dos call returns vector in es:bx 

get offset adr of where to put old int vctr 
store offset of old vector 

store segment of old vector 

need ds for new int vctr seg adr 

load offset:seg of new int vctr in ds:dx 
vectored to when the 8259 interrupts 
OCh=int #(4-1) * 4 

(4 bytes=segment : offset) 

code the 8259 places on 

data bus for 8088 

ah= 25 hex = dos fcn to 

set interrupts 

dos call 

restore ds 

IMR=21h=8259 bus address, get current masks 
reset IRQ4 mask (bit 4=0=>unmasked=enabl ed) 
and store the new mask settings 

disable (clear) interrupts 

nonspecific EOI Cif interrupts enabled) 
send it 
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The ISR differs from most MASM routines in stack segment addressing and 
in precautions needed for the ISR interrupting itself. The problem with the stack 
that can occur when writing ISRs is not having a stack available when the inter- 
rupt fires off. This can happen if the interrupt occurs when the system is exe- 
cuting BIOS code in ROM, or the DOS stack is close to its limit. You might think 
this is not a problem because we can create our own stack, but where do you 
save the segment registers, and how do you load the new ones? The following 


example 


stkchk 
0B 
stksp 
stkchk 
DATA 
reges 
regss 
regsp 
spadr 
DATA 
CHKCODE 
ASSUME 
PUBLIC 
CHKINT 
jmp 
ChkTmpAX 
ChkTmpDSs 
SetSeg 
mov 
mov 
mov 
mov 
ASSUME 
mov 
mov 
ASSUME 
mov 
mov 
mov 
mov 
mov 
ASSUME 
push 


Let's start our examination of this example with the code segment. We will 


solves this problem. 


SEGMENT PUBLIC 


32 DUP ('STACKCHK') ; STACK SEG EASY TO FIND IN DEBUG 
equ $ ; define beginning of stack for chkint 
ENDS 

segment PARA public ‘data’ j;define segment 

dw (7) ; don't use stack - save it here 

dw (?) ; don't use stack ~- save it here 

dw (7) ; don't use stack - save it here 

dw stksp 

ends 


SEGMENT PARA PUBLIC 
CS: CHKCODE,D0S:CHKCODE, ES: CHKCODE,SS:CHKCODE 


CHKINT 
PROC FAR ;define interrupt service procedure 
short SetSeg ; jump over our local storage area 

dw (7) 

dw (7) 
label near ; establish data addressability 
cs:ChkTmpAX,ax ; save ax, ds, & dx in the only segment we 
cs:ChkTmpDS,ds_ ; can address right now - the code segment 
ax, dgroup ; now we establish the addressability of our 
ds, ax ; data segment 
DS: DGROUP 
dgroup:reges,es ; we can now save the other segment registers 
es,ax ; in the data segment 
ES:DGROUP 
dgroup:regss,ss 
dgroup:regsp,sp 
ax, stkchk ; get the address of the stack segment 
SS ,ax ; put it in the ss register 
sp,dgroup:spadr ; get the address of the stack top 
SS:STKCHK 
bp ; finally we can use our stack 
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jump over some data space reserved in our code segment because, until we can 
put the address of our data segment in the ds register, the only thing we can rely 
on is that the code segment is in the cs register. When the interrupt fired off to 
get to our program, the current address was pushed on the existing stack, and 
the cs register was loaded with the place to jump to—CHKINT in this case. 

We then save ax so we can use it as a scratch register, and ds so we can give it 
our own data segment address. Then we load ds with the data segment address 
and now we can store things in our data segment. We still haven't established our 
stack, so we save the remaining two segment registers in the data segment. Now 
we can load the stack segment and stack pointer registers. We didn’t want to do 
this before, because we had interrupted some other program in midstream, 
which had no chance to save its stack registers. We want to be a good citizen and 
restore the interrupted program's stack. Notice that we load sp immediately after 
we load ss. The reason is that the 8088 and later CPUs of the Intel line automati- 
cally inhibit all interrupts for one instruction after the ss register is loaded. This 
enables us to load the spregister right after loading the ss register without fear 
that another program will interrupt our program in between, wreaking havoc 
because we still have an old sp. For example, if our ss:sp will be 1000:100, our 
code segment 1000:200, and the last ss: sp was 2000:0220, then, after we load ss 
but before we load sp, the ss:sp address will be 1000:220. If an interrupt pro- 
gram executes a pushinstruction now, it will overwrite our code. Not every inter- 
rupt program is as nice as ours and sets up its own stack. Many assume there's 
one available and use it without so much as a “by your leave,’ hence, the immedi- 
ate mov sp,dgroup:spadr while interrupts are disabled. 

There may be some cases where the interrupt can fire off while you are in 
the middle of the ISR. Then the ISR interrupts itself. This is like everyone crowd- 
ing onto a boat without letting anyone out. In a short while, there's no room for 
anyone else and the boat sinks. 

The system will crash due to stack overflow if too many ISRs are started 
before any can finish. The solution is to check a flag when the ISR begins, and if 
it is set, exit immediately. Otherwise, set it and reset it when the ISR is done. 

Removing the ISR is simple: 


lds . dx,dgroup:OldVectorAdr ; load offset:seg of old int vetr in 
s ds:dx* vectored to when the 8259 interrupts 


mov ax,250ch ; OCH=IRQ no. (4)+initialized base(8)=int type 
3; code the 8259 places on data bus for 8088 
3; dos fcn to set interrupts 

int 2th : dos call 

pop ds s restore ds 

in al,2th s 21h=8259 bus address, get current masks 

or al,10h s set IRQ4 mask (bit 4=1 => masked=disabled) 

out 2th,al ; and store the new mask settings 
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Parting Shots 


The Programmer's Guide of version 5.0 of MASM may not be your idea of light 
reading, but there are some interesting new features that make it worthwhile. In 
particular, take a thorough look at Chapter 5 which introduces some new ways 
to deal with segments, the model declarations in particular. One of the most use- 
ful for me is the set of predefined equates discussed in Section 5.1.5 of the Guide. 
This allows you to set up general-purpose macros for segment naming based on 
the segment name, or filename. The new documentation provides some very 
nice examples which I won't try to elaborate on here. 

I was also pleased with the “Communal” declaration described in Section 
8.4. This feature allows you to declare variables as Communal in a single include 
file instead of having to declare it public in the procedure it is defined in and 
then external in the procedures it is referenced in. 

One of the most useful new features of MASM 5.0 is the inclusion of the 
Codeview debugger. This window-oriented debugger has many desirable fea- 
tures. It allows you to view your source code (including comments and assem- 
bler directives) as you debug. It also allows you to declare some memory 
locations (by name or address) to be “watch” variables which means they will 
appear in a separate watch window so that you can observe any changes as they 
happen. It supports debugging of Expanded Memory Specification (EMS), over- 
lay programs, and library modules. And for the first time, it allows you to see the 
8087 coprocessor stack and status registers. There are many more features of 
Codeview which make it a very worthwhile debugger, although it lacks several 
features, such as tracing backwards, creating your own window features 
through macro scripts, and saving your session to disk for later review. Don't let 
the fact that Codeview is better than Debug preclude you from considering 
other debugging tools. 

Finally, looking forward to an exciting future, we have the ability to assem- 
ble 80386 and 80387 code in both real and privileged (protected) modes. 

There is much more to macros, interrupts, etc., than we could cover here 
but this leaves the thrill of discovery to you. Nothing in programming is beyond 
you if you have your own PC and an attitude of “WhatifItry this ... ?” After all, 
the worst that can happen is that you have to power off and then on again. 


Reading List 


140 


Biggerstaff, T. 1986. Systems Software Tools. Englewood Cliffs: Prentice-Hall, Inc. 
> This contains readable descriptions of interrupt and communications 
hardware and software on the IBM PC. 
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Dunford, C. 1983/84. Interrupts and the IBM PC. PC Tech Journal. (November/ 
December, January). 

> This contains an interrupt-driven communications program in assembler 
as an example. 


Intel Corporation. 1985. iAPX 286 Programmer's Reference Manual. Santa Clara, 
California. 
> This contains 80286/80287 details and assembly programs. 


. 1986. Microsystem Components Handbook. Santa Clara, California. 
> Go to the source! Not light reading but invaluable. 


Michael Goldman wrote his first program in 1964 when response time was days. 
He wrote his second program in 1972. While waiting for response time to improve, he 
received a B.S. in physics and an M.A. in mathematics from the University of Wiscon- 
sin. He now writes systems-level programs in C and assembly language in Silicon Val- 
ley. Only assembly language feeds his insatiable appetite for ever-faster response time. 


Related Essays 


4 Adding Power to MS-DOS Programming 
13 Programming the Serial Port with C 
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Section Two 


PROGRAMMING TOOLS 
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To compete in the 1990s, MS-DOS programmers not only must thoroughly un- 
derstand the MS-DOS operating system, they must learn how to use many un- 
documented functions that were meant to be reserved for the operating system. 
Also, they must master new standards of functionality such as popup utilities 
and background-processing TSRs, data security, and interfacing with the 
Microsoft Windows operating environment. 

At this stage in its history, the MS-DOS operating system is generally recog- 
nized to be mature, with expected revisions not likely to exceed version 3.5. 
Therefore, more and more programmers are cautiously ignoring the warning 
that undocumented functions are reserved for future features. In fact, many re- 
served functions and interrupts have been used by Microsoft to implement some 
of the earliest external command utilities, and neither these functions nor any 
of the others are likely to be changed. Everything inside the system is now fair 
game for exploitation. 

The name of the game is mastery. The four essays in this section revolve 
around the topic of developing the skill to manipulate—even customize—the 
way in which the MS-DOS kernel handles application programs and their files. 


Undocumented MS-DOS Functions 


This essay leads the section, and in it, author Ray Michels brings together expla- 
nations of most of the important undocumented functions, including those that 
let you examine and manipulate the Program Segment Prefix (PSP), allocate and 
deallocate memory, and inspect the MS-DOS busy flag. With these techniques, 
you can take real control of the internal MS-DOS data structures and services. 
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Safe Memory-Resident Programming (TSR) 


The second essay in this section, by M. Steven Baker, shows how to use docu- 
mented and undocumented interrupts and functions to create stable memory- 
resident programs that do not contend with other memory-resident applica- 
tions. He examines some MS-DOS memory-resident programs such as PRINT and 
GRAPHICS and presents an example of a handy memory-resident utility that lets 
you disable and reenable the PRINT SCREEN key combination. 


Data Protection and Encryption 


Asael Dror, in this third essay, discusses the problem of protecting data from 
unauthorized access. He shows simple methods of using nonstandard charac- 
ters and manipulating file attributes as well as the limitations of those methods. 
He discusses more advanced protection schemes, closing with techniques for ef- 
fectively using RpublicS encryption algorithms. Ultimately, the software de- 
signer must assume that the encroacher is as smart, technically well-equipped, 
and intimately informed as the authorized users, and yet still must be locked out 
of the encryption scheme. 


Inside Microsoft Windows 


In this section's fourth and final essay, Michael Geary explains the fundamental 
concepts behind the Microsoft Windows multitasking operating environment. 
He shows how to use functions to examine the Windows message stream, the 
important circulation of information between the applications and devices that 
inhabit the Windows environment. Finally, he presents his now-famous SPY code, 
a tracing utility that reports details of applications as they run under Windows. 
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Raymond J. Michels 


The MS-DOS Operating System, which has been available now for over seven 
years in several versions of increasing functionality, remains in many ways an 
undocumented system. Dozens of features, interrupts, and internal calls have 
remained secret within Microsoft or known only to a few MS-DOS developers. 
This paper explains some of the more useful DOS functions that have been ne- 
glected in the documentation. Though some of these functions are used inter- 
nally by DOS, their operations can be useful to application programs. 
I have documented the following areas of MS-DOS: 


= Program Segment Prefix (PSP) 
> MS-DOS File Handles 

t Program Environment Segment 
t MS-DOS Memory Management 
> MS-DOS System Variables 


There are still several MS-DOS functions that are either poorly docu- 
mented or not documented at all. The process of documenting all of the “foggy” 
areas of MS-DOS has been an ongoing project of mine for the last four years. 
Much of what I’ve learned is the result of calling undocumented functions and 
observing the results, and disassembling the MS-DOS code itself. A “break-out 
switch” debugger (a resident debugger that can be activated with a special hard- 
ware switch) proved to be one of the best tools for doing this type of work, be- 
cause it allows you to stop the machine and examine the computer system state 
at any time. 

These MS-DOS “secrets” can be utilized in many different ways. By under- 
standing how MS-DOS works, you can write better programs that take advan- 
tage of all of MS-DOS’ internal functions. It is also possible to extend the function 
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of MS-DOS by adding your own functions and utilities. With the advent of OS/2 
and also fast computers (i.e., 80286 and 80386) multitasking functions that emu- 
late OS/2 could be a very desirable feature. In addition, I think that just snooping 
inside of DOS is a fun way to learn about 8086 architecture and operating sys- 
tem concepts. 

Much of the information contained herein is not documented in the 
Microsoft manuals. This implies that this information may not apply to future 
versions of MS-DOS. However, all existing DOS 2.00 to 3.20 versions should work 
(unless stated otherwise). So far, Microsoft has not removed any functions or 
tables from DOS, but if you use undocumented features be sure to test your 
code with every new version of MS-DOS to be sure. The fact that certain func- 
tions are undocumented also implies that they may be destructive if used in the 
wrong way. Be very careful when tampering with the MS-DOS system tables and 
memory blocks described in this paper. The wrong operation can crash your 
System and can even result in loss of file data! 

I have made two assumptions about your level of expertise: You have a basic 
knowledge of 8086 assembly language and have some experience in writing pro- 
grams in it, and you understand how to perform MS-DOS functions via Interrupt 
21h. 

In several of the examples presented in this chapter, I make use of the fol- 
lowing common subroutines: 


> char_out: output a character in the AL Register 
> string out: output string addressed by DS:DX 
> hex_to_ascii: output word in ascii hex format 


> hexb_to_ascii: output byte in ascii hex format 


These routines can be found at the end of this paper. 
We'll start by examining both documented and undocumented aspects of 
the Program Segment Prefix (PSP). 


Program Segment Prefix 
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PSP is a 256-byte block of memory reserved by MS-DOS at program execution 
time. For each program run, a unique PSP is created. Since it contains control 
information related to the associated program, the PSP can also be considered to 
be a Process Data Block (a unique block of data that stores specific system and 
program data for the associated program). MS-DOS file and memory operations 
rely upon having access to the data in the PSP and also use the value of the physi- 
cal PSP segment (its actual segment address in memory) as a unique process 
identifier. 


Chapter 6: Undocumented Functions 


In this section, we will examine each section of the PSP. Those of you famil- 
iar with CP/M may recognize sections of the PSP, since much of the same struc- 
ture of the CP/M program header was retained when MS-DOS was developed 
using CP/M as a guide. This was to minimize the translation of 8-bit CP/M soft- 
ware to 16-bit MS-DOS software. Some of the structures in the PSP are reserved 
by MS-DOS and are also undocumented, so be very careful when changing such 
structures in the PSP. A wrong address or data value can send your program into 
the trash can. 

The PSP segment address for a program can be found easily at startup. For 
com files, the PSP is the value in the CS register. For Exe files, the PSP is the value 
in both the ES and DS registers. The offset address of the PSP is always zero. 
Since the DS register can change when an Ex€ file is run, it is important that your 
program save its value for later access to the PSP and its related fields. Figure 6-1 
shows the PSP in relation to a program. 


OFFSET 0 


Program Segment Prefix 


100 (Hex) 


Your Program 


Top of 
Segment 


Fig. 6-1. PSP and your program. 


The PSP structure is identical for both Com and €XE programs. Finding the 
start of a PSP located outside of your program's environment, such as the PSP of 
a Terminate and Stay Resident program (TSR), is more difficult. (See Essay 7, Safe 
Memory-Resident Programming (TSR), by Steven Baker.) A technique for finding 
these PSPs will be described later in the section on MS-DOS Memory Manage- 
ment. Figure 6-2 shows the layout of a PSP presented in tabular format and in 
the form of an assembly language MASM listing. You may find it useful to run the 
MS-DOS DEBUG program so you can examine the values in your PSP. Simply type D 
0100 at the DEBUG prompt -. This will display the entire PSP of the program that 
you are debugging. Even if you have not loaded a program, DEBUG still sets up a 
default PSP. 


149 


Section 2: Programming Tools and Techniques 


Offeet (HEX) NAME 


MASM STRUCTURE 


0-EXIT_CALL Dw : 
¢-BLOCK_LENGTH pw 
oB ? 
$2-CPM_CALL f is : DUP (?) 
¢A-EXIT_ROUTINE = : 
$E-CTRL_C__ROUTINE ia : 
12-FATAL_ERROR oy ; 
16-PARENT_ID oaks 
18-HANDLE__TABLE STD IN “sion T ERA mo vo | LSTOUT race | ne (7) 
é 
20-ENVIRONMENT [9 | oe oy 
2E-USER STACK ; pp 
Dw ? 
32-FILE HANDLE COUNT i : 
34-HANDLE TABLE ADDRESS 
2)—> Fil 
50-DOS CALL DB 24 DUP (?) iller 
3 DUP (? 
S5C-DEFAULT_FCB DB DUP (?) 
| OB 10 DUP (7) —» Filler 
G DB 16 DUP (?) 
ae. : TH 
? 
ec-SECOND_Fo8 pave [Ne—-[ Tp t8 UC 
Saad es Se aT Se 
: DB 4 DUP (?) 
DB 128 DUP (?) 


80-COMMAND_LINE 


“__ 

(__ 
Fig. 6-2. PSP structure. 
Overview of the PSP 


Let's take a look at the contents of the PSP and try to make some sense of it. 

The first 2 bytes of the PSP are machine codes to generate an INT 20H which 
is the interrupt used to terminate a program. Thus, calling address 0 any time 
from within your program will cause it to execute the INT 20H. Your program will 
terminate and return to MS-DOS. This is a holdover from CP/M where a jump to 
address zero of your program would exit you to the system prompt A>. This 
method of program exit is not advised in MS-DOS since MS-DOS versions 2 and 
above provide better ways to terminate a program by using Function 4Ch via INT 
21H, the main MS-DOS function interrupt. This DOS function allows you to set a 
return code that can be examined in a batch file or from a calling program. It 
may also perform better housekeeping and cleanup when your program termi- 
nates. 

The next word in the PSP is called block length and contains the total 
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amount of memory available in paragraphs in this PC. One paragraph is 10h 
bytes. Reading this address can be useful for quickly determining if there is 
enough memory available for your program's needs. If, for example, you know 
your program needs 512K bytes of memory and the PSP block length field re- 
ports only 256K bytes, appropriate action can be taken (such as reporting there 
is not enough memory available). 

Byte number five of the PSP contains machine code to perform MS-DOS 
functions. Calling this location (similar to the old CP/M Call) is equivalent to per- 
forming an INT 21H. The function number is placed in the CL register prior to 
calling offset 5. Note that this differs from the traditional INT 21H convention of 
placing the function number in the AH register. Other registers may be needed 
but they vary for each function. This is another holdover from CP/M and is re- 
ferred to among MS-DOS aficionados as the “ancient system call.’ MS-DOS func- 
tions should never be performed in this manner and don’t use this value, but it 
allowed easy porting from CP/M to MS-DOS. 

Starting at offset OAh are three double-word (32-bit) pointers, each in the 
form of an offset address and a segment address. They are pointers to the Exit 
routine, the Control-c routine, and the Fatal Error routine. These are copies of 
Interrupts 22h through 24h from the standard interrupt vector table in the base 
page of memory (segment 0,offset = 0). When your program exits back to 
MS-DOS, these values will be copied back to the interrupt vector table. This is 
done just in case your program modified these values for its specific needs (such 
as installing its own Critical Error Handler). 

The next two components of the PSP are undocumented. The first contains 
the Process Id of the parent process. What this means is that this word, starting 
at 16h, points to the PSP of the program that initiated the “current” program. 
(The original program will still be in memory.) By using the documented Func- 
tion 4Bh, one program can initiate another. The second component is a table of 
20 bytes starting at 18h in the PSP. These locations are used to manage file han- 
dies. Remember, a handle in MS-DOS is a method of file access. The size of this 
table is the reason that one program can only open 20 files at a time. 

The environment pointer for our program starts at offset 2Ch in the PSP. 
This is the segment address of the program's environment-each program in 
memory has a unique environment. 

The double word at offset 2Eh is used by DOS to store the caller's stack 
segment and stack pointer when DOS switches to an internal stack during INT 
21H processing. 

The two components starting at offset 32h deal with the File Handle Table 
(FHT). The word at offset 32h contains the maximum number of file handles and 
the FHT’s size for the program. Offset 34h contains a DWoRD (double-word) 
pointer to the FHT. DOS does not seem to be affected by changing these values. 
They can be used when you need the number of file handles and the address of 
the handle table. 

Starting at offset 50h are machine instruction bytes to perform a DOS func- 
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tion call INT 21Hand RETF. If you set up your registers properly and perform a FAR 
call to location PSP:50h, the INT 21H will be executed (performing the desired 
DOS function) and when DOS returns, the RETF will return back to your code. 

Three well-documented sections of the PSP are at locations 5Ch, 6Ch, and 
80h. Offset 5C contains an unopened File Control Block (FCB) if a file was speci- 
fied as a program parameter on the command line, as in DIR FILE1. If a second 
file was specified (COPY FILE1 FILE2), its associated FCB will be found at 6C. These 
FCBs at 5C and 6C are yet another CP/M holdover. Location 80 contains the en- 
tire command line following the program name. This can be useful when pass- 
ing program switches such as the /Pin D1IR*.* /P. Your program can examine the 
data at offset 80 and recover this information. Since locations 5C and 6C only 
create FCBs, location 80 is needed if full pathnames (such as \SYSTEM\FILE) are 
used as command-line file parameters. 

The PSP can be considered the heart of your program. It controls your file 
access and also is used for memory allocation. It paves the way for a multitasking 
environment since it could be used as a unique process identifier and control 
mechanism. Let's move on and look more closely at the File Handle Table and the 
Environment Pointer sections of the PSP. 


File Handles 
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One of the major changes in MS-DOS with the release of version 2.00 was the 
introduction of file handles to the operating system. A handle is a byte value 
assigned to an opened file. All subsequent operations performed on the file only 
require the handle number and not a full FCB. MS-DOS keeps track of the FCB 
for you in its own System File Table (SFT). 

As we have seen, the FHT, located at offset 18 (hex) in the PSP segment, is a 
table of 20 bytes. When an operation that uses a file handle is performed, DOS 
uses the handle number to index into this table. DOS then uses the number re- 
trieved from the table to locate the actual file in the SFT. (See Essay 10, Develop- 
ing MS-DOS Device Drivers, by Walter Dixon.) The following handles are opened 
for you when your program is loaded: 


0- Standard Input 

1- Standard Output 

2- Standard Error Output 
3- Standard Auxiliary I/O 
4- Standard Printer Output 


The remaining 15 bytes of the FHT are available for your program's data 
files. This table size is what limits your program to using 20 files (five of which 
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are already used). The FILES=nn in the CONFIG.SYS file sets up how many file 
blocks are available for the entire system. If FILES=40, a TSR can use 20 files and 
your program can use 20 files. Figure 6-3 descibes how DOS uses the file handle 
number to get to its internal SFT. 


(1] 
Handle number assigned by DOS 
and used by your program 


Index into 
handle table 


RY AW VEY AVY LY EY LV AYE EVEYEVEY, 
a | oo fe [oe ee [ee oe en ee 


File Handle Table 


Table Entry 


Index into 
system 
file table 


System File Table 


Fig. 6-3. File handles in action. 


What does this method of file access achieve? Since, in MS-DOS, the Console 
Input and Output are opened as file handles (remember that these are numbers 
and not names), it is very easy to substitute an actual disk file for console output or 
input. (Standard Error, COM1 and LPT can also be accessed through file handles.) 
This is exactly what DOS does during a request for I/O redirection: DIR*.*>file.A 
disk file is opened with a file handle and the console output handle is replaced by 
the disk file handle. The UNIX operating system (where this idea came from) uses a 
similar concept for managing its files. Since the first five file handles are already 
open, it is very easy to perform I/O on these devices by just using the appropriate 
handle number in the documented MS-DOS file output Function 40h: 


mov ah,40H swrite to a file with handle function 
mov bx,1 3;Standard Output handle 
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mov cx,? swrite 7 bytes to Standard Output 
mov dx,offset msg ;DS:DX points to data to output 
int 21H ; 


msg db ‘'Hello',13,10 


This example would write the message Hel Lo (defined with db) to the stan- 
dard output (either the Console Output or the current redirection device). 
MS-DOS Function 3Fh will perform a similar operation except that it will input 
data (rather than output) from the specified file handle to the specified address 
in the DS register. 

File handles also moved DOS a step closer toward a multitasking operating 
system. The actual file information is maintained by MS-DOS. This enables mul- 
tiple programs to gain access to the same file without any conflicts. 

What can we do with this PSP File Handle Table? It is possible, under pro- 
gram control, to alter this table to redirect files on your own. Redirection is a 
good feature, but at times it would be nice to be able to turn it on and off during 
program execution. This feature could be used to print screens to files for docu- 
mentation use, for error-logging or for program-debugging. The following code 
fragments demonstrate how to change from printing, to the console, to redirect- 
ing the console output to the printer: 


redirect proc near 


this procedure will redirect the console output to the printer 


=a =e =e 


sassumes DS:BX points to start of PSP segment 


les bx, (bx+34h) ;get handle table address 
mov al,es:(bx+1] ;get current std output handle 
mov save_console,al s;save it 
mov al, [bx+4] get current print output 
mov [Cbx+1],al ;put it in console spot 


snow all output to the standard output will be directed to the 
sprinter 


redirect endp 


cancel_redir proc near 


Chapter 6: Undocumented Functions 


this procedure will cancel the redirection set up in redirect 


=e =e =e 


sassumes ES:BX points to file handle table 


mov al,save_console ;get original console value 
mov [bx+1],al sput it back 


redirection is now canceled 


=e ee ae 


cancel_redir endp 
save_console db (7) 


In this example, we can change the I/O direction of any file just by altering 
the FHT. Make sure you remember to save the original table entry before any 
changes are made. 


The Environment Segment 


In our earlier discussion of the PSP, we mentioned that it contains a pointer (at 
offset 2Ch) to the program's environment. This address is a segment number 
with an offset of 0. As its name implies, the environment identifies specific pa- 
rameters that can be used by the associated program. The environment is 
sparsely documented in the IBM DOS Technical Reference. Let's look at it more 
closely. 


Variables in the Environment 


The environment contains a series of ASCIIZ strings (a string of ASCII characters 
terminated by a null (0) byte). Each of these strings can have specific meaning 
either to DOS or your own program. An environment string is set up at the com- 
mand prompt by entering a command with the form SET VARIABLE = (String pa- 
rameter), for example, SET PATH= \SYSTEM. This will place the string following the 
SET command into the next available environment slot. MS-DOS reserves three 
environment variables, COMSPEC, PATH and PROMPT. The COMPSEC variable is always 
set by MS-DOS at boot time and it defines the path and name of the command 
processor (usually COMMAND.CoM, but a custom command processor could also be 
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used). The COMSPEC variable can be useful to the application program when exe- 
cuting another program or MS-DOS commands such as DIR or ERASE (by using 
the MS-DOS exec Function 4Bh where COMMAND.COM is being used to execute a 
command). The PATH variable identifies the current search path for command 
execution, so when you type a command, MS-DOS knows which directory paths 
to search for it. PROMPT is used for generating a user-defined prompt. Both the 
PATH and PROMPT commands are well-documented in the DOS Reference Manual. 
Additional variables can be set up for application program use. 

A good use of environment variables is to allow the user to identify where 
application specific data or parameter files are located at the time a program is 
run. Using this method, files accessed by your program that would otherwise 
have had to be in a predefined place (either in a specific directory or in the cur- 
rent directory) can be placed in a directory chosen by the user. This feature 
could be used to support multiple, unique data sets that can be accessed by a 
single program. A batch file can change the environment variable to point to the 
desired data. In Microsoft C, a function called GETENV is provided (and docu- 
mented) in version 4.0 to gain access to environment variables. For other lan- 
guages, you will have to search the environment space to locate the specific 
variable of interest. 

A null byte follows the last ASCIIZ string defining variables. For MS-DOS 
versions 2.XX, the environment ends here. In version 3.00 and above, this is fol- 
lowed by a word called a byte count. However, I have always found this to be 
“one. An ASCIIZ string specifying the full PATHname of the current application is 
next. For example, if the program name were ENVI.COM and its path 
C:\SYSTEM\UTIL, the string will contain C:\SYSTEM\UTIL\ENVI.COM. It will be ter- 
minated by one null to end the program name string. This single null byte also 
marks the end of the environment data. We will use this string later in an exam- 
ple that prints out a memory map of resident programs. 


Using the Environment in Batch Files 


A feature of environment parameters (undocumented until DOS 3.30) is that 
they can be easily accessed from and used within a batch file. For example, sup- 
pose that you have issued the command SET USER=NOVICE at the MS-DOS com- 
mand line. The value of the variable USER can be obtained from inside a batch file 
by enclosing it in percent symbols. The following line: 


IF ZUSER% == "NOVICE" TYPE HELP.TXT | MORE 


could be used inside a batch file to output a special help file through the MS-DOS 
MoRE filter. The | (pipe) instructs MS-DOS to take the standard output from the 
first program and use it as data to the standard input for the second program. 
MORE displays a screenful of text and waits for a key to be hit before continuing. 
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Another interesting batch file trick is to use environment variables in such 
a way as to allow callable subroutines within a batch file. These routines can be 
called and then return control to a specified label in the batch file. It is really just 
an intelligent GoTo. The following batch file example describes this technique: 


SET RETURN=ONE Set up a ‘return’ label 

GOTO SUBROUTINE Perform the subroutine 

sONE Subroutine will ‘return’ here 
SET RETURN=TWO Set up a ‘return’ Label 

GOTO SUBROUTINE Perform the subroutine 

:TWO Subroutine will ‘return’ here 
GOTO END Exit this batch file 

: SUBROUTINE Subroutine to call 

ECHO INSIDE OF SUBROUTINE Subroutine Body 

GOTO ZRETURN% ‘Return' to caller 

:END 


Environment variables thus add a new dimension to batch file program- 
ming by moving the batch language close to a real programming language. DOS 
3.30 has added the capability of having one batch file call another as though it 
were a subroutine. 


Expanding Environment Space 


When setting environment variables, the error message OUT OF ENVIRONMENT 
SPACE may be encountered. The size of the initial environment for the command 
processor sets the environment size of all subsequent programs. The default 
size varies by DOS level and MS-DOS distributor and it can be changed by speci- 
fying a shell program in the CONFIG.SYS file. The default shell is COMMAND.COM. We 
will still use COMMAND.COM in the example, but by using the documented SHELL 
statement in the CONFIG.SYS file, we can alter the size of the initial environment. 
The syntax of the statement is as follows: 


SHELL = Cs:COMMAND.COM /P /E:nn 
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The first parameter /P tells COMMAND.COMto become permanent (be kept in 
memory) as the top-level process, and cause the AUTOEXEC .BAT file, if present, to 
be executed. The second parameter /E:nndefines the environment size, and ap- 
plies to MS-DOS versions 3.00 and above only. For versions 3.00 and 3.10, the nn 
defines the number of paragraphs to allocate (one paragraph equals 16 bytes) 
and this value can be from 10 to 62 (giving environment sizes from 160 to 992 
bytes). For MS-DOS 3.20 and 3.30, the nndefines the absolute number of bytes to 
allocate to the environment, from 160 to 32768. Remember, each program in 
memory gets its own environment so setting a large environment will waste 
memory if a number of TSRs are used. 

When COMMAND. COMexecutes a program, it makes a copy of its own environ- 
ment (the one affected by the SETcommand) and attaches this environment to 
the new program. When the program terminates, its environment, along with 
the PSP and executable image, is returned to free memory (unless it is a TSR). 
This is an important fact since programs that alter the environment are only 
accessing a COPY of the master and any changes will only be in effect while the 
current program is executing and has not terminated. This also applies to a pro- 
gram executed or started from a program other than COMMAND.COM (as in a child 
process). 


PSP Functions 
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Table 6-1 lists the five functions useful for manipulating the PSP segment. The 
last three are undocumented. Let's briefly examine the documented functions 
first. 


Table 6-1. PSP Functions 


Function Operation 

Function 26h Create PSP Block 

Function 50h Set Current PSP 

Function 51h Get PSP Segment 

Function 55h Duplicate PSP Block 

Function 62h Get PSP Segment (DOS 3.00 and above) 


Function 26h Create PSP Block 


MS-DOS Function 26 will create a PSP block at the memory segment address 
specified in the DX register. Prior to the EXEC call’s (Function 4Bh) being available 
(starting with DOS 2.0), Create PSP Block was a way to have one program “chain” 
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to another (that is to create a child process). It is up to the main program to 
create/allocate the memory space required for the new program. Function 26 
should be avoided since the EXEC Function 4B now does a much better job. 


Function 62h Get PSP Segment 


Function 62 will return the current PSP segment in the BX register. This function 
is not available prior to MS-DOS version 3.00. In version 2.XX, the undocumented 
Function 51h performs the same operation and it is still available in later ver- 
sions. It is rumored that Function 51 has a bug when used from a resident pro- 
gram, so use Function 62h whenever this service is required. The bug is that 
DOS switches to the wrong internal stack. This will cause problems if called 
from a TSR during an jnterrupt 28h. 


Function 50h Set Current PSP 


Function 50 (along with Function 62) is best used from within a TSR. Since the 
PSP segment is unique for every program, it is used as a Process ID by DOS for 
file handling and memory allocation. Function 50, Set Current PSP, is called with 
the AH register equal to 50h and the BX register equal to the desired PSP seg- 
ment number (Process ID). We'll say more about these soon. 


Function 55h Duplicate PSP Block 


This function is almost identical to Function 26. The new PSP segment is passed in 
the DX register and, on return, a new PSP is initialized. The major difference is 
that the Parent ID portion of the PSP is set up by MS-DOS. Function 55 is used by 
Function 4B when executing a new program. It could be useful to you if you need 
to execute a program but want total control (as in a multitasking environment). 
The following steps could be used to develop a method to execute a program: 


. Allocate memory for the PSP and program code. 

. Duplicate the PSP. 

Load your code into newly allocated segment above the PSP. 
Save current PSP. 

. Set PSP to newly duplicated one. 


aon fF wo nN 


. Jump to start of code. 
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Undocumented TSR and PSP Secrets 


The two most useful PSP functions are 50h, Set Current PSP, and 51h (or 62h), 
Get PSP Segment. They are generally used from inside a TSR. 

In MS-DOS, each process can only have a maximum of 20 files open at one 
time. If a process terminates with open files, they will automatically be closed by 
MS-DOS. This can cause confusion if a TSR uses files without adjusting the pro- 
gram segment. For example, if a TSR opens a file, DOS will use the File Handle 
Table in the current (foreground) PSP, which does not belong to the TSR but to 
the program the TSR interrupted. This could cause the foreground process to 
run out of file table space since it didn’t expect a TSR to be using its files. It can 
be even more disastrous if the foreground process terminated since this would 
close the TSR’s file as well! A TSR-performing memory allocation/deallocation 
can cause similar problems since it may be modifying the foreground process 
memory pool instead of its own. Because of this, a TSR needs to save its PSP 
segment during initialization for later use during file operations and/or memory 
allocation/deallocation. 

Another useful idea using the Get PSP call is that a TSR can access the fore- 
ground program's environment. Different TSR operations could be run based on 
an environment variable’s setting. 


Memory Management 
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One of the major features that DOS 2.00 added to 1.00 was the ability to allocate 
and deallocate memory as needed. The concepts used are similar to those used 
in the UNIX operating system (and other multiuser systems). Each program in 
memory can get a block of memory and shrink or expand it based on its needs. 

There are documented MS-DOS functions available that deal with memory 
management (listed in Table 6-2). The MS-DOS manual does not explain these 
fully, especially for a novice programmer. 


Table 6-2. Memory Management Functions 


Function Operation 
Function 48h Allocate Memory 
Function 49h Free Memory 
Function 4Ah Adjust Block Size 


Memory Allocation Blocks are referenced in paragraphs and one para- 
graph equals 16 bytes. To convert a memory value in bytes to a memory value in 
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paragraphs in a program, just add 16 to the value and binary shift the result to 
the right four times. This rounds the value up by one paragraph and divides by 
four. To convert back, binary shift it to the left four times. Let's briefly take a look 
at these memory management calls. 


Function 48h Allocate Memory 


Allocate Memory requests a block of memory from the MS-DOS pool of free 
memory. Place the Function number 48h in the AX register and the number of 
paragraphs required in the BX register. On return, if the Carry Flag is set, then 
BX contains the maximum number or paragraphs available. Note that no actual 
allocation takes place in this case. To allocate memory, you must call the function 
again with BX less than or equal to the total amount available. If the Carry Flagis 
clear, the memory is allocated, and AX contains the segment address of the allo- 
cated space. If you want to allocate as much memory as possible, call this func- 
tion with BX equal to FFFFh. This request will never be granted but it will return 
the maximum amount of memory available for allocation. 


Function 49h Free Memory 


Free Memory is the opposite of allocate. It will return the specified block of 
memory back to the system memory pool. You must free the entire segment allo- 
cated by a Function 48h call. Place Function 49 in the AX register and the seg- 
ment address of the memory block to free in the ES register. On return, if the 
Carry Flagis set, the operation failed and AX will contain the DOS error code. An 
error is usually caused by specifying a segment of memory that does not belong 
to your program. 


Function 4Ah Adjust Block Size 


Adjust Block Size is a request to change the size of a currently allocated block of 
memory. You can shrink or expand a previously allocated memory block with 
this function. Place Function 4A in the AX register, the segment address of the 
block to modify in the ES register, and the new block size (in paragraphs) in the 
BX register. If the Carry Flag is set, BX will contain the maximum number of 
paragraphs available; otherwise, the operation was successful. To find the maxi- 
mum amount of memory available use the same technique described for Func- 
tion 48 (call with Bx = FFFFh). 

In MS-DOS, when COMMAND. COMloads your program, all the available system 
memory is allocated to that program, so if the program is a TSR, it will need to 
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deallocate all that extra memory before terminating. MS-DOS programs also 
have the ability to call other MS-DOS programs, but if another program is to be 
loaded, some memory must be freed up to make room for the new program. The 
MS-DOS Exec Function 4Bh is used to execute other programs. For those of you 
familiar with Pascal, MS-DOS memory functions are similar to the New and 
DISPOSE functions. 

Now that we have briefly touched upon the MS-DOS memory functions, 
let's take a look at the undocumented physical structure of these memory blocks 
that can be created. By understanding how these blocks are organized, it is pos- 
sible to write a program that reports the status of all allocated memory blocks 
that can be very handy for debugging purposes. As an example, we will describe 
a technique for printing out a map of all programs currently in memory. 

Every official memory block created by MS-DOS has a 10h byte (one-para- 
graph) Memory Control Block (MCB) physically preceding it. (Since both the envi- 
ronment and the PSP segments are allocated by MS-DOS, they each have an 
MCB.) Thus, any memory blocks that your application program allocates for 
holding data will have an associated control block. To find the MCB for a specific 
segment, simply subtract one from the segment address. This will be the allo- 
cated block's corresponding MCB. (Since segment numbers are the leftmost four 
digits of a five-digit value, subtracting one is the same as subtracting 10h). The 
following is a MASM data structure for an MCB. These control blocks are linked 
together to form a chain of MCBs. 


MCB Signature db O ;(MCB = Memory Control Block) 


MCB Owner dw OO ;(Segment of owner - Usually PSP 
5 segment) 
MCB Size dw O ;Cin paragraphs) 


The byte called signature can be either 4Dh or 5Ah. A 4D signifies that this 
is an MCB. Because the MCBs are a linked list, the 5A signifies the last block in the 
allocated chain. 

Owner specifies which segment owns this block, and is generally the owner's 
PSP segment address. Remember, the PSP is used as a unique process ID. By us- 
ing the Owner field, DOS can ensure that one program (such as a TSR) does not 
attempt to alter the size of another program’s memory block. This protection is 
only valid when using DOS memory allocation/deallocation functions. 

Size specifies how many paragraphs are contained in this block. By adding 
the size value to the segment address of the MCB and then incrementing the 
result by one, you are able to access the next block in the chain (provided that 
the current signature is not 5ADh, indicating the end of the chain). Figure 6-4 
shows a chain of Memory Control BLocks. 

There is no way to go backward in the MCB chain. This makes it tough for a 
program to find out information about any TSR installed or a parent process. 
But there exists an undocumented way to get to the start of the MCB chain. DOS 
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Signature Owner Size 
ie cen | ete 


Memory 
Control! 
Block (MCB) 


Allocated 
Memory 
Block (AMB) 


500 (hex) bytes allocated 
Last Block in Memory CHAIN 


Fig. 6-4. A memory control block chain. 


Function 52h returns a pointer to a number of special DOS variables. One of 
these variables happens to be a pointer to the first MCB. Using this value, we can 
create a program that will start at the beginning of the MCB chain, trace 
through all allocated blocks, identify PSP segments, and generate a memory 
map of the system. The environment segments can be found from the environ- 
ment pointer in the PSP segments. The following is a MASM module that will 
print out selected information about allocated memory. It works in this manner: 


. Get memory block. 

. If it is a PSP, print its MCB’s segment address. 
. Print PSP's segment address. 

. Print size of PSP in paragraphs (from MCB). 


. Print program name (from environment). 


anh WOW DH - 


. Print PSP’s parent name (from Parent ID). 


mcb struc 
Signature db 0 
owner dw 0 
size dw 0 
mcb ends 
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begin: 


lLoop1: 


mov 
call 
call 


call 


call 
pushf 
call 
popf 
jnc 


mov 
int 


get_first_mcb 
sget first mcb returns pointer in ES:BX 


push 
mov 
int 
sub 
mov 
mov 
xor 


cle 


pop 
ret 


get_first_mcb 


get_next_mcb 
sget next mcb 
sassumes ES:BX pointer to current MCB 


& 


push 
mov 
inc 


add 
mov 
cmp 
je 

stc 


dx,offset headO ;print headers 
string_out 

get_first_mcb j;get memory blocks and process 
process_mcb 

get_next_mcb 

process_mcb 

loop1 

ah,O sexit to dos 

2th 

proc near 

ax 

ah,52h sget DOS Variables 

21h 

bx,2 sget first MCB pointer 
ax,es: [bx] 

es, ax 

bx, bx 

ax 


endp 


proc near 


ax 
ax,es sget MCB segment address 
ax spoint to actual allocated 


; memory block 
ax,es:[bx.size] ;add in block size 


es,ax snow we point to next block 
es: (bx.signature] ,4dh 
get_all_ok 


sflag end of chain 


jmp 
get_all_ok: 
cle 
get_exit: 
pop 
ret 


get_next_mcb 


Chapter 6: Undocumented Functions 


get_exit 


ax 


endp 


process_mcb proc near 
7Print pertinent field of device driver header 
sInput: ES:BX points to device driver header 


;Output: None 


push 
push 
push 
push 
push 


cmp 
je 
jmp 
ispsp: 
mov 
call 
mov 


LO: 
mov 
call 
loop 


mov 
call 
mov 


l1: 
mov 
call 
loop 


mov 


ax ;save registers 
bx 
cx 
dx 
si 


byte ptr es:[bx+16],0CDh ;Is It PSP? 
isipsp 
process _ exit 


dx,es 
hex_to_ascii 
cx,4 


al,’ ‘ 
char_out 
LO 


dx,es:{bx.owner]) 
hex_to_ascii 
cx,4 


al,’ ‘ 
char_out 
L1 


dx,es:([bx.sizel] 
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call hex_to_ascii 
mov cx,4 
l2: 
mov al,’ ' 
call char_out 
Loop l2 
push es 
call extract_prog_name 


process_loop: 


push ds 
push es 
pop ds 
xor cx,0 


process _loop1: 


Lodsb 
inc cx 
call char_out 
cmp byte ptr CsiJ,0 
jne process_loop1 
mov ax,13 
sub ax, cx 
mov CxX,ax 
\3: 
mov al,’ ' 
call char_out 
loop \3 
pop ds 
pop es 
push es 
push bx 
push ds 
mov ax,es:[bx+26h] sget PID 
dec ax spoint to MCB 
mov bx,0 
mov es, ax 
call extract_prog_name 
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push 
pop 
xor 
process_loop3: 

lLodsb 
inc 
call 
cmp 
jne 


mov 
sub 
mov 


L4: 
mov 
call 
Loop 


pop 
pop 
pop 
mov 
call 


process exit: 
pop 
pop 
pop 
pop 
pop 
ret 
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es 
ds 
Cx, CX 


cx 
char_out 

byte ptr (Csi],0 
process_loop3 


ax,13 
ax,Cx 
CX, ax 


al,' 
char_out 
L4 


ds 

bx 

es 

dx,offset crlf 
string_out 


si ;restore registers 
dx 
cx 
bx 
ax 


process_mcb endp 


extract_prog_name proc near 


e 


7es:bx -> psp 


;returns es:si -> prog name 


push 
push 
pop 


ds 
es 


ds 
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mov ax,es:[bx+3ch] ;get environ segment 
cmp ax,0 

jne extract_cont 

pop ds 

push ds 

pop es 

mov si,offset command 

ret 


extract_cont: 
mov ds,ax 
xor si,si 


not_found: 


cmp word ptr ([siJ,0 

je found 

inc si 

jmp not_found 
found: 

add si,4 


not_found’: 
cmp byte ptr ([si],0 


je found1 

inc si 

jmp not_found1 
found1: 

dec si 

cmp byte ptr [sil,'' 

jne found! 

inc si 

push ds 

pop es 

pop ds 

ret 


extract_prog_name endp 


data 


=e 0 =e 
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headO label word 


db 149,' MCG PSP PROG (PARAGRAPHS) *,13,10 
db ' SEG SEG SIZE NAME PARENT ',13,10 
db ‘'---- ae Soo tc oweremee soceresenn-— ",13,10 
crlf db 2,13,10 
command db ‘COMMAND.COM' ,O 


The following is a sample of the output produced by the preceding program: 


MCB PSP PROG (PARAGRAPHS) 
SEG SEG SIZE NAME PARENT 


0D34 0D35 00c3 COMMAND.COM COMMAND.COM 


OEOF 0E10 0058 SYSTEM COMMAND .COM 
OE73 OE?74 0037 KBDFIX.COM COMMAND.COM 
OEB2 OEB3 18ED SK.COM SK.COM 


27A8 27A9 0040 GRAPHICS.COM COMMAND.COM 
27F1 27F2 780E PMCB.COM COMMAND. COM 


Other Undocumented Functions 


The following functions don’t really fall into a definitive group so they have been 
placed in this section. They are: 


> Numerous Dummy Functions 

> Function 37h Set Switch Character 

tf Function 52h Get MS-DOS Variables 

> Function 1Ch and 32h Get Disk Parameters 
> Function 45h and 46h Duplicate File Handles 


Functions 45 and 46 are documented but have some undocumented side effects. 


MS-DOS Dummy Functions 


The following functions are not used by MS-DOS: 
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18h 

1Dh 
1Eh 
20h 


VVYVYV 


Many of the lower numbered functions of MS-DOS have an equivalent CP/M 
counterpart. These CP/M functions were not implemented by MS-DOS but were 
probably left in to ease the porting of CP/M to MS-DOS based software by keep- 
ing the succeeding function numbers the same. These are described in MS-DOS 
manuals as “reserved” 


Function 34h Get MS-DOS Busy Flag 


After performing an INT 21H with AX equal to 34h, ES:BX will point to a byte 
called the MS-DOS busy flag. When this byte is nonzero it indicates that MS-DOS 
is in use. This function is generally used by a TSR to make sure that it is safe to 
perform MS-DOS functions. Since MS-DOS is not reentrant, calling DOS while it 
is busy will usually corrupt its stack and cause a system crash. You should not 
call MS-DOS every time a flag check is needed. The proper procedure is to call 
this function once and store the value returned in ES:BX for use during the cur- 
rent activation of the TSR. When a later check on this flag is required, use the 
previously stored ES:BX value to examine the flag value. If the flag is nonzero 
when your TSR is activated, it means that you have interrupted the main (fore- 
ground) program performing a DOS function. 


Function 37h Get/Set Switch Char 


The Switch Char is the character that precedes command-line switch (hence the 
name). In the command DIR /P, the character / is called a switch character. The 
directory structure of MS-DOS was patterned after the UNIX operating sytem, 
but with one small (and sometimes frustrating) difference. In UNIX, /BIN/FILEis 
a legal filename. In MS-DOS, it would have to be called \BIN\FILE. Notice that the 
filename separators are reversed. This is because the / was already used. At one 
time, there existed a command that could be put in the CONFIG. SYS file that could 
alter the switch character. Many people prefer to use - for a command-line 
switch and / for directory separators. By changing the switch character from /, 
the directory separator will revert to the UNIX format. Though this command 
has been removed in DOS 3.XX, you can still change the switch character 
through Function 37h. When the switch character is changed from /, the direc- 
tory path can use either \or / as a separator. '- 
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Function 52h Get DOS Variables 


Function 52 returns a pointer to block of data values that can be called DOS 
variables, also referred to as List of Lists (see Essay 11). These variables either 
point to or contain relevant system information about the disk drives, file sys- 
tem, device drivers, and a few other items. The returned pointer will be in the 
ES:BX register set. 

The following MASM structure describes the layout of the table: 


VARS STRUC 
dpb_ptr dd 0O 3BX+0 
sft_ptr dd 0 sBX+4 
clock_ptr dd 0 5BX+8 
con_ptr dd 0 3BX+0CH 
max_sec dw QO ;BX+10H 
cache dd 0 3;BX+12H 
drive_inf dd 0 3BX+16H 
fcb_ptr dd 0O 3BX+1AH 
unknown dd  0O 3BX+1EH 
nul_dev dd 0 3BX+22H 

VARS ENDS 


The order of this table seems to vary with versions of DOS and OEM imple- 
mentation. The preceding table was taken from DOS 3.20. 

The first element in the table, at offset BX + 0, is a pointer to the Drive or 
Device Parameter Block (DPB). The DPB is a block of data that contains specific 
information about each MS-DOS physical disk drive. We will examine the DPB in 
detail a little later. 

The second element, at offset BX + 4, is a pointer to the MS-DOS SFT, con- 
taining information about all open files. There is another file table pointer at 
offset 1Ah which points to a table of files opened with the older style FCB access. 

The third and fourth elements, at offsets BX + 8 and BX + OC (hex), are 
pointers to the Clock and Console Device Drivers, respectively. 

The next element, at offset BX + 10h, is a maximum sector size value. This is 
set to the largest sector size being used internally by MS-DOS prior to loading 
block device drivers. After device driver initialization, this value is compared to 
the sector size returned by the device driver. If the device driver's sector size is 
greater, MS-DOS prints an error message Sector Size Too Large and the driver is 
not installed into DOS. 

Offset BX + 12h contains a pointer to the MS-DOS cache buffer head. I have 
not been able to decipher the buffer structure. 

At offset BX + 16h is a pointer to a series of blocks containing such drive 
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information as the current directory of a particular drive. The last element, at 
offset BX + 22h, is the start of the NUL device driver. The first two words of a 
device driver is a pointer to the next driver. Since the NUL device is always first, 
we can follow the device driver chain until these first two bytes are FF FF (- 1) in 
the last device driver. When debugging device drivers, it can be very helpful to 
know where in memory they are located. Using this information, you can exam- 
ine data inside the driver. With the proper debugging tools, you can even set a 
break point in the driver code itself. 

An item that is not actually part of the DOS variable table can be found at BX- 
2. This word points to the first MCB. Remember, we used this value to display infor- 
mation about all of the MCBs. Again, it should be stressed that any values found in 
the variables table, or data pointed to from the table, should not be altered. They 
are best used in a read-only mode. These values control many important operations 
of MS-DOS such as file I/O, Device Handling, and Memory Management. 


Drive Parameter Blocks 


The Drive Parameter Block (DPB) is a table created by MS-DOS during system 
initialization. Every logical drive has an entry in this table. (Logical is used to 
access each drive, A: B:, but may not be a physical disk drive. It could be a 
RAMdisk or one hard disk with multiple drives.) These entries describe all pa- 
rameters necessary for MS-DOS to maintain a file system on the disk drives. The 
following MASM structure defines the layout of the DPB: 


dpb struc 


dirty_flag db 
next_dpb dd 
dpb_unknown dw 
dpb ends 


lLogical_num db ? 
drive_num db ? 
sector_size dw ? 
spa db ? gsectors per allocation unit (cluster) 
shift db ? sshift factor (2“shift)-1 = spa 
reserved dw ? 
number_fats db ? 
number_dirs dw ? 
data_start dw ? 
alu dw ? snumber of allocation units 
fat_size db ? 
dir_start dw ? 
device_drv dd ? 
media db ? 
? 
? 
? 
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The first entry, Logical_num, is the logical drive number (A = 0,B = 
1... ). This is used to identify the table entry if searching for a specific disk drive. 

The next entry, drive_num, is the drive unit within the associated device 
driver. Since device drivers can control multiple units (drives), each unit is as- 
signed a sequential unit number within the driver. DOS will need this number to 
“talk” to the device driver. 

sector_size is the sector size in bytes. The next entry, spa, contains the 
number of sectors per allocation unit. An allocation unit, or cluster, is the small- 
est unit that DOS can allocate for a file. 

reservedis the number of reserved sectors before the File Allocation Table 
(FAT). Usually this is a one, reserving a sector for the B00T information. If the 
device is not bootable, such as a RAMdisk, its value will be zero so that no sectors 
will be wasted. 

number_fats defines how many FA/Ts are contained on the disk drive. Most 
MS-DOS implementations keep two copies of the FAT table for data integrity. 

number_dirs defines how many directory entries can reside in the ROOT di- 
rectory. 

data_start defines what sector the file data begins. This comes directly af- 
ter the FATs and the directory. atu defines how many allocation units make up 
the disk drive. Dividing aluby spa gives you the total number of sectors available 
for data. 

fat_size defines the size of each FAT in sectors. dir_start defines the 
starting sector of the directory. device_drvis a pointer to the device driver that 
controls this disk drive. Using this value, MS-DOS can “talk” to the disk device 
through the device driver. 

media is the media descriptor byte. This is usually the first byte in the 
MS-DOS FAT and usually identifies the current disk type. This is especially useful 
for identifying floppy drives where you can insert single and double-sided flop- 
pies. 

The DPB can be used when a program needs to know where the FAT starts, 
or where the directory is located. Usually these programs will of be a diagnostic 
type. A program that scans a disk containing data for bad sectors and then re- 
ports what files contain bad sectors would require most of the information in 
the DPB table. The scope of this paper does not allow us to develop an extensive 
program but the following MASM code fragments describe how the data in the 
DPB can be utilized: 


load_fat proc near 


;load the fat into memory starting at address DS:SI 

smake sure you have a large enough buffer 

sCall this procedure with ES:BX pointing to a DPB 

70n return if Carry Set then an error occurred 

sThis routine will use the Documented MS-DOS Interrupt 25 Chex) 
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; Absolute Disk Read 


push ax 

push bx ssave registers 

push cx sint 25h uses a Lot of regs 

push dx 

push bp 

push di 

push $i 

push es 

push ds 

mov dx,es: (bx. reserved] sget starting FAT sector 
mov cx,es:[Ebx.fat_size] snumber of secs to read 
mov al,es:[bx.logical_num] ;drive number to read 
mov bx,si starget offset for FAT read 
int 25h ;do the disk read 

jne good_exit 


error_exit: 


popf spop flags left on stk by int 25 
stc sflag carry as error 
jmp final_exit 


good_exit: 


popf spop flags left on stk by int 25 
cle 


final_exit: 


pop ds srestore registers 
pop es 
pop si 
pop di 
pop bp 
pop dx 
pop cx 
pop bx 
pop ax 
load_fat endp 
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read_all_sectors 


proc near 
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r 

sthis procedure will read all data sectors 
;(starting after reserved,fat and dir sectors) 
scall with es:bx pointing to DPB 


push 
push 
push 
push 
push 
push 
push 
push 
push 


mov 
mov 
mov 
shl 
add 
push 
mov 


inc 
mov 
mul 
mov 
pop 
mov 


read_loop: 


push 
mov 
push 
mov 
push 
push 


ax 
bx 
cx 
dx 
bp 
di 
si 
ds 
es 


ax,es:{bx.dir_start] 
bx,es:(bx.number_dirs] 
cl,8 

bx,cl 

ax, bx 

ax 

cx,es:[bx.spa] 


ax 

ax,es:Calu] 

cx 

CX, ax 

dx 
al,es:[bx.logical_num) 


cx 

cx,1 

dx 

bx ,offset sector_buffer 
ax 

bx 


;save registers 
smost destroyed by int 25 


sget directory start 
snumber of dir entries 


e 

smultiple by 32 

sax is data start sector 
ssave start sector 
ssectors per alloc unit 


3# of alloc units 

sget # of sectors 

sput in cx for loop 
sget data start sector 
sdrive to read 


sread 1 sector 


sregister are not 
ssaved by INT 25 
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push 
push 
int 
je 
popf 
pop 
pop 
pop 
pop 


process sector 


=e Se We 


pop 
inc 
pop 
loop 
cle 


jmp 
read_error: 


pop 
pop 
pop 
pop 
stc 


exit: 


pop 
pop 
pop 
pop 
pop 
pop 
pop 
pop 
pop 


read_all_sectors 


sector_buffer 


cx 
dx 
25 


read_error 


dx 
cx 
bx 
ax 


data here 


dx 
dx 
cx 


read_loop 


ex 


dx 
cx 
bx 
ax 


es 
ds 
si 
di 
bp 
dx 
cx 
bx 
ax 


h 


it 


endp 


db 


;increment sector to read 
srestore loop counter 


shere if error on read 


;restore registers 


312 dup (7?) 
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Functions 1Fh and 32h 


Undocumented functions 1F and 32 return pointers to the DPB. There are two 
major differences between using these functions and getting to the DPB via the 
DOS variables: 


1. These functions need to access the disk drive when called. This can be 
inconvenient if it is an empty floppy drive since you will get an “Abort, 
Retry, Ignore” type error. 


2. The table pointer returned is based on a specific drive, whereas the DOS 
variable DPB pointer places you at the start of the table. Function 1F re- 
turns information on the currently logged disk drive while Function 32 
allows you to specify a disk drive. 


When calling these functions, place the function number in AH. For Func- 
tion 32, place the drive number in DL (0 = default, A = 1...). On return, 
DS:BX will point to the appropriate table entry. It may be easier to use these func- 
tions than the DOS variable pointer when dealing with specific disk drives since 
you don’t need the extra code to search for the specific table entry. The DPB 
examples given in the previous section will work just as well with these func- 
tions. 


Functions 45h and 46h: Duplicate Handles 


These two functions are documented in MS-DOS reference guides but they have 
some additional undocumented uses. Function 45h duplicates an existing file 
handle into another file. The BX register contains an open file handle and, on 
return, the AX register contains a new duplicate handle. This gives you two sepa- 
rate file handles referencing the same files. Function 46 takes two different file 
handles and forces them both to refer to the same file. Register BX contains the 
file handle to duplicate and CX contains a handle that will be force duplicated. If 
the original file in CX is open before the INT 21H call, it will be closed first. 

The directory and FAT information are not updated for an open file handle 
until that file handle is closed. If you have large amounts of data to process and 
the system crashes in the middle of a file output process, all output is pretty 
much lost. (You could rebuild pieces of the file sector by sector but that could 
take a long time.) The obvious solution is to close the file periodically to update 
the directory entry and FAT, but all of this opening and closing means a lot of 
DOS overhead. In DOS 3.3, Funtion 68h is called Commit File and will flush the 
file's buffers and update the disk. 

The best solution is to use Function 45h to create a duplicate of your open 
file handle. Whenever you want to update the file information, simply close the 
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duplicate file. The next time an update is needed, open and close a duplicate 
handle again. Just keep in mind that this additional file handle reduces the num- 
ber of files that you can have open (15 files after the MS-DOS default files are 
opened). 

In the PSP section, we discussed altering the file handle table to affect redi- 
rection. Function 46h can also change redirection. Since Function 46 takes two 
file handles and makes them one, we can create a redirection. For example, sup- 
pose we want to redirect the console output to a file that we have opened. Let’s 
call the console FILE_CON and the opened disk file FILE_DISK. First we want to 
make a duplicate of FILE_CON. Since we are going to be changing the standard 
output file, we want to save it for restoration later. Let's call the duplicate 
FILE_SAVE. By doing this, we would call Function 45h with BX containing 1 (the 
file handle for Standard Output). On return, save the value of the AX register. 
This will be our FILE_SAVE. Next we will call Function 46h to force the FILE_CONto 
be a duplicate of FILE_DISK. For this operation, load the BX register with the file 
handle number of FILE_01SKand the CX register with 1. After processing the INT 
21H request, all output to the standard output file FILE_CON will go to the disk file 
FILE_DISK. To restore things to the way they were before the redirection, we 
need to put the old console output FILE_SAVE back. Again we will call Function 
46h. Load the BX register with the handle value store as FILE_SAVE and the CX 
register with 1. When the function is complete, all is restored. (Don’t forget to 
close the file FILE_D1SK.) (For all those out there still using FCB open calls instead 
of file handles, you can see that you can do much more with a file handle.) 


Undocumented Interrupts 
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There are three undocumented MS-DOS interrupts that can be useful to pro- 
grammers. They are: 


> Interrupt 28h DOS Safe Interrupt 
> Interrupt 29h Console Device Output 
‘> Interrupt 2Eh Back Door To Command Processor 


Interrupt 28h DOS Safe Interrupt 


I call this function the DOS Safe Interrupt because, when this interrupt is issued 
by MS-DOS, it is safe to use Functions OCh and above-if the DOS Busy Flag is not 
greater than 1. It only appears to be called when DOS is waiting for keystrokes 
(as the command processor COMMAND.COMis waiting for keystrokes at the system 
prompt). As soon as the first key is hit, this interrupt is no longer called. This 
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enables resident programs to take advantage of the fact that the system is sitting 
idle. A resident process that operates concurrently with the foreground process 
could use this as a flag that the system is not being used and “steal” more time 
away from the foreground. The only MS-DOS program that uses this interrupt is 
the background print spooler PRINT.COM. This interrupt is generally used in con- 
junction with DOS Function 34h (DOS Busy Flag) to perform background opera- 
tions. 


Fast Console Output 


Interrupt 2Ah appears to be a back door into the console output device driver. 
The character in AL is output to the console when this interrupt is performed. 


Back Door to Command Processor 


MS-DOS provides a method for one program to execute another through the 
EXEC Function 4Bh. Though this function is very useful, there also exists a “fast 
and dirty” method of executing commands. The undocumented Interrupt 2Eh 
appears to be a back door into the command processor COMMAND .COM. To execute 
an MS-DOS command, simply shrink memory down to make room for the new 
program (as in Function 4B) and perform an Interrupt 2E with the DS:SI register 
set pointing to a parameter string. This string has its length as the first byte, the 
command to perform (such as 01R *.*), and a carriage return (ODh) to terminate 
the string. The carriage return is counted as part of the string length. On return, 
make sure you reset your stack again since this interrupt may not save the SS:SP 
values. The following MASM fragment will execute a DIR *.* command from 
within a program: 


mov bx,end_of_code sset to end of our code space 
mov cx,4 sshift count 

shr bx,cl sdivide by 16 

inc bx sa Little extra 

mov ah,4ah sadjust memory block 

int 2th 

mov si,offset parameter ;get command string 

int 2eh s;do command 

push cs sreset stack 

pop ss 


cli 
mov sp,offset stack 
sti 
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parameter db 8,'‘DIR *.*',Odh 


end_of_code equ $ 


Common Subroutines 


We have examined many documented and undocumented MS-DOS features that 
will enable you to write better, more efficient programs. The following are the 
common subroutines promised at the beginning of this paper: 


char_out proc near 


e 


print character in al to the standard output device using 


7MS-DOS funtion #2 


push dx 
mov dl,al 
mov ah,2 
int 21h 
pop dx 
ret 
char_out endp 
string _out proc near 


ssave register used to 
: output character 
;set up for DOS function call 


scall MS-DOS 
;restore register 


sprint a string pointed to by DS:DX 


;first byte of passed string is 


push ax 
push bx 
push cx 
push dx 

mov ah,40h 
mov bx, dx 
inc dx 

xor ch,ch 
mov cl, (bx) 
mov bx,1 
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string length 


;save registers used 


;MS-DOS Write To File Handle 
sget string address in BX 
;point to actual text of string 
;zero out ch register 

sget length byte of string 
sstandard output handle 
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int 2th scall DOS 
pop dx srestore registers used 
pop cx 
pop bx 
pop ax 
ret 
string_out endp 
hex_to_ascii proc near 


soutput word value in DX as a 4-digit ASCII HEX Number 
sto the standard output 


push cx ssave registers 
push ax 
mov cx,4 sloop Counter (4 hex digits) 
hex1: 
push cx ssave loop counter 
mov cl,4 srotate count 
rol dx,cl sswap high word and low word of 
30x 
mov al,dl sget byte 
and al,Ofh sturn into nibble (4 bits) 
daa screate printable ASCII character 
add al,OFOh °(0-9 or A-F) 
adc al,040h 
call char_out soutput the character 
pop cx ;restore loop counter 
loop hex1 sgo back for more 
pop ax srestore registers 
pop cx 
ret 
hex_to_ascii endp 
hexb_to_ascii proc near 


soutput byte value in DX as a 2-digit ASCII HEX Number 
sto the standard output 


181 


Section 2: Programming Tools and Techniques 


push cx ssave registers 

push ax 

mov cx,2 ;loop Counter (2 hex digits) 
hex2s 

push cx ;save loop counter 

mov cl,4 srotate count 

rol dl,cl ;swap high and low nibble of DX 

mov al,dl ;get byte 

and al,Ofh ;turn into nibble (4 bits) 

daa ;create printable ASCII char 

add al,OfOh :(0-9 or A-F) 

adc al,040h 

call char_out ;output the character 

pop cx srestore Loop counter 

loop hex1 790 back for more 

pop ax ;restore registers 

pop cx 

ret 


hexb_to_ascii endp 
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M. Steven Baker 


Die ability to support memory-resident programs is an interesting and useful 
feature of MS-DOS. An ordinary MS-DOS program is loaded from disk on each 
execution and removed from memory after its operation is terminated. If you 
want to run the program again, you must reload it from disk. A memory-resi- 
dent program remains in memory even when it is no longer running. Thus, such 
programs are often called Terminate and Stay Resident (TSR) programs. 

A TSR program can be reactivated at any time, even while another pro- 
gram is running. This is usually done by typing a specified character sequence at 
the keyboard. Some TSR programs are reactivated by other events, such as the 
movement of a mouse, a specific time event, or information from some other 
hardware event. Reactivating a TSR program suspends the execution of what- 
ever other program is running. When the TSR program is exited, it becomes 
dormant again and the program that was running resumes. Several TSRs can be 
in memory at the same time, although this can sometimes cause conflicts, de- 
pending on how the programs were implemented and how they are activated. 


Why Are TSRs Useful? 


Perhaps the most familiar type of TSR in use today is the desk accessory pro- 
gram, such as Borland’s SideKick or Lotus’s Spotlight. These programs fulfill the 
need for computerized desk accessories by providing facilities such as a notepad 
editor, calendar, calculator, phone list (similar to a rolodex), phone dialer, and so 
on. Most of the utility of such a program comes from the fact that its functions 
are available at the touch of a key or two, regardless of what you are doing at the 
time. For example, you can activate a calculator desk accessory while in the 
midst of writing a letter using your favorite word processor. Then you can per- 
form some calculations and “paste” the results of the calculation back into your 
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letter, all without leaving the word processor. If the calculator were not a TSR, 
you would have to exit your word processor, run the calculator program and 
save the results to a temporary file, exit the calculator program, restart your 
word processor, and finally read in the file with the results in it. 

In addition to the desk accessories, some other popular examples of com- 
mercial TSR programs include ProKey, Turbo Lightning, and Ready. ProKey is 
typical of many keyboard macro programs that allow the user to program a se- 
ries of keystrokes onto a single keystroke for convenience. Other similar TSR 
keyboard programs include Superkey and Smartkey. Turbo Lightning includes a 
spelling checker and thesaurus available at the touch of specified keys. The spell- 
ing checker can be set up to automatically beep at you if a misspelled word is 
typed. Ready is a sophisticated outline processor which can be activated in the 
middle of another program. Popup graphics programs such as Graph in a Box 
make it easy to graph data in a spreadsheet or database. Programs such as In- 
stant Recall provide freeform database features. 


TSRs in MS-DOS 


Another type of TSR is actually installed as an extension to the hardware envi- 
ronment or the operating system. These TSRs include keyboard macro pro- 
grams, mouse driver programs, networking hardware support, hardware cards 
for communication with IBM mainframes, print spoolers, and the like. 

You have probably used a number of TSR programs in your everyday use of 
MS-DOS, perhaps without realizing it. The MS-DOS operating system comes 
with several TSR utility programs. Starting with the earlier versions of DOS, 
these include MODE, PRINT, GRAPHICS, and ASSIGN. 

TSR programs can be found for a diverse range of other applications and 
offer two main advantages to the user: 


> the ability to extend or enhance some features of MS-DOS (for example, 
replace a long string of key commmands with a few keystrokes) 


t» the convenience of having several programs accessible at virtually the 
same time (within the limitation of MS-DOS’ being able to actually run 
only one program at a time) 


Today, many PC users would feel lost without their favorite assortment of 
TSRs supporting their work environment. 


The Origin of Memory-Resident Programs 
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The MS-DOS operating system has its roots in the CP/M-80 operating system 
written by Digital Research for 8-bit microcomputers based on the Intel 8080, 
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8085, and Zilog Z80 microprocessors. The early versions of MS-DOS were very 
similar to CP/M-80. However, one large difference stands out between these ear- 
lier 8-bit microcomputers and the IBM PC. The older machines can only directly 
address 64K bytes of memory, while the IBM PC-based machines can address 
1024K. (Actually, the IBM PC has only 640K of memory available for user pro- 
grams, since memory above this point is used or reserved for the video display 
adapters, hard disks, ROM BIOS, and other purposes.) Any way you look at it, a 
jot more memory is available for programs on the PC than with the previous 
generation of machines. Under CP/M, memory was precious. 


CP/M Programs 


Any enhancements to CP/M (i.e., keyboard macros or function keys) were nor- 
mally incorporated into the machine specific part of the operating system (the 
BIOS) written by the computer manufacturer. These enhancements were limited 
by how much memory they could take from the basic 64K. If the operating sys- 
tem grew in size, less memory would be available to run your favorite applica- 
tions such as WordStar, SuperCalc, and dBASEII. Since these features were 
chosen by the manufacturer, the user could not customize them. However, even 
under CP/M, some memory-resident programs were developed and used even at 
the expense of the memory required. Three popular TSRs under CP/M were 
Smartkey (a keyboard macro program), Uniform (a utility to allow reading and 
writing various CP/M disk formats), and Unspol (a public domain print spooler 
similar to PRINT under MS-DOS). 


Early MS-DOS Features 


A TSR feature was incorporated with the earliest version of MS-DOS. Seattle 
Computer Products (SCP) was the original author of MS-DOS. The earliest com- 
mercial release of 86-DOS version 0.3 (as it was called then) offered a TSR func- 
tion well over a year before the operating system was purchased by Microsoft 
and became MS-DOS. The purpose of this operating system function call was to 
allow extensions to DOS to be added easily to the operating system, particularly 
user-written interrupt handlers. A program could be loaded that enhanced 
MS-DOS and then remained resident in memory. New enhancements or device 
support could be added to MS-DOS without rewriting the operating system. 
This was all made possible by the ability to address and use more memory. But 
memory only seemed to be less precious under MS-DOS than it had been under 
CP/M. Soon we were complaining about the “640K barrier” 

The version of MS-DOS customized and sold by IBM was called PC-DOS, 
version 1.0. PC-DOS versions before version 2.0 did not have the option of user- 
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installable device drivers, but TSR programs provided a somewhat equivalent 
feature. For example, early multifunction cards by AST and other manufactur- 
ers would come with TSR programs for the realtime clock, RAMdisk and print 
spoolers. 

The only TSR program distributed with PC-DOS and MS-DOS version 1.XX 
was the MODE program, which incorporates several video and device control fea- 
tures. The memory-resident part of MODE allows output to the DOS parallel 
printer to be redirected to the serial port. Why was it necessary to incorporate 
this feature as a TSR? In fact, this reveals one of the major deficiencies of 
MS-DOS from its beginning—the operating system was designed with very poor 
support for printers. 

Under PC-DOS and most versions of MS-DOS, the printer device is assumed 
to be a parallel port (designated LPT#1). However, a user might have a serial 
printer or plotter instead or even two printers—a dot matrix draft printer and a 
letter quality printer. The MS-DOS operating system did not support sending 
printer output to anything but this one parallel port device. The MODE program 
provides a mechanism to redirect output normally sent to a parallel printer port 
to be sent to one of the serial ports instead. 

Why was the MODE program written as a TSR? The inconvenient alternative 
would have been for every program written for MS-DOS to have an installation 
procedure and support routines to send any printer output to either the 
MS-DOS parallel printer device or to serial ports (on the IBM PC, designated 
COM1 and COM2). Another possibility would have been to invoke something 
similar to MODE as part of each program you used. Clearly, the TSR mechanism 
makes more sense. When TSRs are used, the changes in configuration remain in 
memory and operate transparently—no application program has to be changed, 
and nothing else has to be reloaded. 


Later MS-DOS Programs 


With the introduction of MS-DOS version 2.0 by Microsoft, several TSR utility 
programs were included with the operating system for the IBM PC: 


PRINT.COM 
" MODE.COM 
ms  GRAPHICS.COM 
r= ASSIGN.COM 


wv 


PRINT is a memory-resident print spooler of limited usefulness. It is similar 
to the earlier public domain UNSPOL program used under CP/M-80. PRINT allows a 
file to be printed in the background while another application is operating. 
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While MS-DOS is waiting for keyboard input or while noncritical functions are 
happening, PRINT can send a text file to the printer as a background task. This 
program assumes that the file to be printed is an ASCII text file. 

PRINT expands any tabs in a file based on tab settings every eight spaces and 
considers the 1AH character (the old CPM end-of-file character) to mark the end 
of file. Binary or nontext files can be sent to the printer properly as long as they 
don’t contain any embedded TAB (09) or EOF (1Ah) characters, but it isn’t easy to 
guarantee such files don’t have these characters. Effectively, this precludes using 
PRINT to spool graphics files to the printer, many formatted text files to daisy 
wheel printers, or font files to laser printers. The TAB or EOF character in these 
files may mean which pin to fire on a dot matrix graphics dump, or may be part 
of the character definition in a font file. 

Why does PRINT need to be a TSR? A print spooler needs to be memory- 
resident so that it can function even though several other applications are 
started and stopped. 

Three other simpler TSRs were included with MS-DOS 2.X. The MODE pro- 
gram, which we have discussed, allows redirecting parallel printer output to the 
serial ports. GRAPHICS is a memory-resident addition to the PRINT SCREEN func- 
tion. This program allows full screen dumps to an IBM graphics printer or com- 
patible printer from a graphics image on an IBM Color Graphics Adapter (CGA) 
or compatible adapter and display. This program is only of use when the display 
is in one of several possible graphics video modes. For convenience, since GRAPH- 
ICS was written as a TSR, it only needs to be invoked once. 

ASSIGNis a memory-resident utility that assigns logical disk drives to actual 
drives in a system. The ASSIGNcommand provides the ability to run programs on 
a hard disk system even though they were written assuming only one or two 
floppy disk drives are available. ASSIGN maps calls through a logical disk (A 
through H) to another physical disk. This utility modifies disk calls passed to the 
operating system. 


Microsoft and TSRs 


The background print spooler showed, for the first time, the appearance of ac- 
cessing two programs at the same time and provided an example of its imple- 
mentation. MS-DOS is still a single-user system, but the sense of task-switching 
was demonstrated. This “simulated multitasking’ naturally attracted the interest 
of software developers, but as with other aspects of the operating system, 
Microsoft provided only limited details on the 8086 interrupts and DOS function 
calls that support these new TSR system features. Thus TSR-supporting features 
were discovered by programmers trying to emulate and extend the features em- 
bodied in the TSRs supplied with MS-DOS. The result, as we have seen, has been 
the development of a considerable variety of TSR programs. 
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At the same time, Microsoft expressed a general policy of not supporting 
the concept of TSR programs. Why would Microsoft incorporate TSR features in 
MS-DOS and not document them and support them? The most likely reason is 
that they conflict with long-term goals of making MS-DOS into a true multitask- 
ing operating system like OS/2. Most TSR programs are not “well-behaved” and 
depend on taking control of some system hardware. This makes true multitask- 
ing and multiuser operation difficult if not impossible to implement. Neverthe- 
less, because widespread use of OS/2 is still in the future, and many users will 
continue to use existing versions of DOS, TSRs will continue to be written and 
used for some time. 


Types of TSRs 


Let's step back a bit and try to categorize the current flood of TSR programs. 
First, there are the simplest extensions to MS-DOS itself such as GRAPHICS, MODE, 
and the various RAMdisk utilities. These programs extend a hardware feature 
on the IBM PC and do not need to use any MS-DOS function calls. Other exam- 
ples of this first type would include the various SETCLOCK programs that replace 
the MS-DOS time function calls to a realtime clock. The MS-DOS AssIGNn utility is 
a TSR that maps MS-DOS disk calls from logical to actual disk drives in the sys- 
tem. The distinguishing features of this class of TSR is that, once resident, no 
DOS function calls are made by the TSR. 

The second class includes the more complex TSRs that, once resident, must 
make DOS function calls (such as for file reading and writing). These TSRs are of 
two types: DOS extension and utility programs and application programs. In the 
first category are keyboard enhancement programs that allow reading and writ- 
ing keyboard macro files “on the fly’ The second type includes most of the spe- 
cialty programs that must make DOS function calls and provide some task- 
switching features. These programs may extend MS-DOS with a printer spooler 
like PRINT, but more likely they provide some popup application program very 
conveniently at the touch of a “hot key,’ as with SideKick. 


Well-Behaved Memory-Resident Programs 
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The main concerns in writing TSRs are trying to create a well-behaved program 
and making certain that other TSRs already loaded are also allowed to function. 
The simpler class of TSRs (such as GRAPHICS) are much easier to write than the 
second class (such as PRINT). Again, the distinguishing feature is whether MS- 
DOS function calls must be made from the TSR. This fact is reflected in the size 
of the sample TSRs provided with MS-DOS listed in Table 7-1. 
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Table 7-1. MS-DOS TSR Program Sizes (bytes) 


en er 


Program Version 2.0 Version 3.1 Version 3.3 
GRAPHICS 789 3,111 7204 
ASSIGN 896 1,509 1530 
PRINT 4,608 8,291 8995 


The difficulty in TSRs like PRINT, SideKick, Ready, etc., is determining when 
DOS or an application program is interruptible. This problem exists because 
MS-DOS function calls are not reentrant or recursive, i.e., you cannot “stack up” 
several calls. If an MS-DOS function call is in progress and our TSR interrupts 
and makes another MS-DOS call, the first call will be trashed and lost with un- 
pleasant side effects for the primary application. As well, the ROM BIOS Diskette 
—IO interrupt INT 13H is also not reentrant. For example, if a disk read was 
started by the foreground program seeking to a particular track, and we inter- 
rupted before the reading took place and invoked an MS-DOS call requiring file 
access and the disk interrupt, the first seek would be lost upon reentering the 
Diskette__IO INT 13H routine. 


The 8086 and Interrupts on the IBM PC 


In order to learn how to write TSR programs, you must understand, in at least a 
limited way, the underlying hardware and software structure. The IBM PC is 
based on the Intel 8088 microprocessor chip, which is a member of a family of 
similar chips including the 8086, 80188, 80186, 80286, and 80386. From a pro- 
grammer’s perspective, all these chips can be programmed as if they were an 
8086 microprocessor. The 80186, 80286, and 80386 chips include some en- 
hanced hardware and software features that need not be used. The V20 and V30 
microprocessors from NEC (Nippon Electric Corporation) are also extensions to 
the basic 8086 that have software extensions similar to the 80186. 

These chips can all address at least 1024K bytes of memory. The lower 1024 
(400h) bytes of memory on all these chips is special, set aside as a table of 256 
(100H) possible interrupt vectors. Each interrupt vector consists of a double- 
word pointer to a location in memory. On the 8086, an interrupt can mean either 
a hardware interrupt (generated by a device or processor) or a software inter- 
rupt (triggered by executing the INTinstruction). The INTinstruction is a special 
software instruction on the 8086 CPU family that pushes the CPU’s flag register 
onto the stack, disables hardware interrupts, and invokes the instructions 
pointed to by the particular interrupt vector in this table. These instructions 
may be invoked by specific hardware conditions or by software instructions. 
TSRs are usually interrupt driven. 
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As an example, we will look at the first few interrupt vectors. Interrupt 0 is 
invoked if the 8086 chip divides by 0. At address 0 in memory, we would find a 
pointer to software to handle cases of hardware divided by zero. The first word 
of this pointer is the offset of the routine to invoke and the second word is the 
segment. The IBM ROM BIOS sets this interrupt to point to an IRETinstruction in 
the ROM BIOS. This just does nothing and returns from the interrupt. The 
debug command on an IBM PC under DOS 3.1 will show something like the fol- 
lowing: 


-d0000:0000 OOOT 
and the debug output will show 


0000:0000 €8 4E 2f 01 FO 01 70 OO-5F F8 OO FO FO 01 70 00 .N/ 


oeePo_eee 


The Interrupt Vector Interpretation is 


Location Offset, Segment Description 

000d dw 4EE8h, 012Fh s INTERRUPT O Divide_by_zero (DOS) 

0004 dw 01FOh, O0070h s INTERRUPT 1 Single-step (BIOS) 

0008 dw OF85Fh,OFO0O0Oh s INTERRUPT 2 Nonmaskable interrupt (ROM) 
000Ch dw 01FOh, O070h s INTERRUPT 3 Breakpoint (BIOS) 


Some of these vectors are special to the microprocessor itself. Intel has re- 
served vectors 0 through 31 (0-1FH) for internal use, although only a few are 
used on the 8086. Others are used by the hardware peripheral devices, which 
interrupt the operation of the microprocessor, for example, when a key is 
pressed. Finally, most of these vectors are used by the operating system software 
for invoking various functions and as pointers to special data structures in mem- 
ory. All communication with the MS-DOS operating system is through the use of 
these interrupt vectors. When a TSR program is loaded in memory, it replaces 
some of these existing interrupt vectors with pointers to itself. (See Essay 1, A 
Guided Tour inside MS-DOS, by Harry Henderson, for a general discussion of 
interrupts. See Essay 10, Writing a SOUND Device Driver, by Walter Dixon, and 
Essay 6, Undocumented MS-DOS Functions, by Ray Michels, for discussion of 
many of the MS-DOS software interrupts. See the last part of Essay 5, Advanced 
MASM Techniques, by Michael Goldman, for a discussion of interrupt process- 
ing.) 

When an interrupt is invoked, the 8086 flags register is pushed onto the 
stack, the current instruction pointer is pushed onto the stack, and hardware 
interrupts are disabled to prevent a hardware interrupt from breaking into the 
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processing of the current interrupt. Figure 7-1 shows what the stack looks like 
upon execution of a software or hardware interrupt. 


8086 Flags 


Segment 


Instruction Pointer 
(offset) 


Fig. 7-1. The 8086 stack upon interrupt. 


MS-DOS version 2.0 and above provide several documented as well as un- 
documented functions that support the TSRs that are provided with the operat- 
ing system. Based on material I have read, I would assume that most authors of 
TSRs have determined these undocumented DOS features by disassembling DOS 
itself and PRINT, for example, and not from information willingly provided by 
Microsoft. This is how I discovered these hidden features. Let’s first look at the 
documented features. 


Documented TSR Support 


MS-DOS provides documented support for three functions relating to TSRs. 


Terminate and Stay Resident INT 27H 


The original function is INT 27H, the Terminal but Stay Resident function that 
goes all the way back to Seattle Computer Products 86-DOS. This function is the 
traditional method for MS-DOS programs to remain resident upon termination. 
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Note that this function affects several other interrupts in the same way as a nor- 
mal termination (Interrupts 22h, 23h, and 24h are restored to the values that 
existed before invoking the TSR program), so it cannot be used to install perma- 
nently resident Ctrl-Break or Critical Error Handler routines. The maximum size 
of memory that can be made resident by this method is 64K (it is actually about 
63.9K since DX cannot be above OFFFOH). Open files are not automatically closed 
by this function. We can summarize INT 27H with the following: 


Entry: CS = segment of PSP 
DX = offset of last byte + 1 (relative to PSP) to be made res- 
ident 


Returns: Does not return to process 


Keep Process INT 21H Function 31h 


MS-DOS 2.0 and above added another equivalent Keep Process call INT 21H (Func- 
tion 31h) used by a program to terminate and stay resident. From Microsoft's 
perspective, this is the preferred function. This function allows the return of an 
exit code to the calling process and allows for larger (greater than 64K) resident 
code. With INT 21H, we have 


Entry: AH = 3th (DOS Function) 
AL = return code 
DX = memory size to reserve in paragraphs (16-byte blocks) 


Returns: Does not return to process 


Multiplex Interrupt INT 2FH 


The least-used documented TSR function is the Multiplex Interrupt INT 2FH also 
called the Print Spool Control function in some MS-DOS documentation, which 
may be used for interprocess communication. This interrupt is used by PRINT to 
pass information to an already resident PRINT spooler (TSR) in memory. However, 
it may also be used by other processes. Each multiplex interrupt handler is as- 
signed a specific multiplex number. The multiplex number is specified in the AH 
register. The specific function requested is specified in the AL register. The mul- 
tiplex numbers AH = 0 through AH = 7Fh are reserved for DOS. Application 
programs are supposed to use multiplex numbers COh through FFh. To avoid a 
conflict between two applications using the same multiplex number, the multi- 
plex number used by a program should be patchable. Function 0 (Get Installed 
State) is currently the only function that must be defined uniformly by all INT 2FH 
handlers. INT 2FHis summarized by 
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Entry: AH 
AL = function code 


multiplex number 


other registers as needed 
Returns: AX = error code if unsuccesful (carry set) 


Function 0 Get Installed State is summarized by 


Entry: AH = multiplex number 
AL = 0 
Returns: AL = status (0, 1, or FFh) 
AL = 0 (not installed, okay to install) 
AL = 1 (not installed, not okay to install) 
AL = FFh (already installed) 


This interrupt was not documented until DOS 3.X versions of the IBM DOS 
Technical Reference Manual, although it was used by the MS-DOS PRINT Utility 
from MS-DOS 2.0 onward. The MS-DOS 2.0 PRINT utility makes calls with AH = 0 
and AH = FFh which are not documented, as well as the documented calls. 


Print Spool Multiplex Handler INT 2FH 


IBM DOS Technical Reference Manual 3.1 describes the Print Spooler Multiplex 
(AH = 1), the resident part of PRINT.COM, in detail. DOS version 3.2 added two 
additional predefined DOS Multiplex Handlers, ASSIGN (AH = 2 is the resident 
part of DOS 3.X ASSIGN) and SHARE (AH = 10h) is the resident part of SHARE. How- 
ever, the earlier ASSIGN command in DOS 2.x did not use this interrupt handler. 
DOS version 3.3 added multiplex handler (AH = B7h), the resident part of APPEND. 

Further functions of INT 2FH are summarized by 


Entry: AH 
AL = 0 Get print spooler installed status) 
AL = 1 (submit a file to be printed) 


AL = 2 (remove a file from the print queue) 


1 (resident Part of PRINT.COM) 


AL = 3 (cancel all files in queue) 

AL = 4 (hold print jobs for status read) 

AL = 5 (end hold for status read) 

DS:DX segment:offset of packet address if Function 1 
segment:offset of ASCIIZ file specification if Function 
2 (remove file) 
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Returns: carry clear if successful 
for Function 0 
AL = status (0, 1 or FFh) as defined above 
for Function 4 
DX = error count 
DS:SI pointer to print queue 
Returns: carry set on error 


AX = error code 


For Function 1 (submit file to be printed), the packet is five bytes long. The 
first byte contains the level and the next four bytes contain a double-word pointer 
of an ASCIIZ file specification (the filename cannot contain wildcards). The level 
byte under DOS 3.1 through 3.3 is 0. For Function 2, wildcards (* and ?) are per- 
mitted in the filespec, allowing multiple files to be deleted. For Function 4, the 
pointer returned for the print queue points to a linked list of ASCIIZ strings. Each 
entry in the queue is 64 bytes long, and the last slot has a zero first byte. 


Undocumented DOS TSR Support 


The following MS-DOS function calls have not been documented in any of the 
IBM technical reference manuals although they are used by the TSRs supplied 
with MS-DOS. 


IN_DOS or DOS_CRITICAL Function 


The first undocumented MS-DOS function call used by TSR programs returns a 
byte pointer to a flag in MS-DOS itself. I have seen this function referred to as 
IN_DOSand also as DOS_CRITICALin a few articles. If this byte flag is 0, then DOS is 
not currently active and therefore any DOS call can be made without trashing an 
active DOS call. This flag is not just a logical flag, but represents a count of recur- 
sive calls into MS-DOS. This function cannot be called any time you wish, how- 
ever. Since it goes through the MS-DOS function entry and stack switch routine 
with interrupts enabled, allowing interruption, this function cannot be called 
while MS-DOS is executing another function or interrupts are disabled. Thus a 
TSR program when it is first loaded by COMMAND.COM during initialization will 
make an MS-DOS Function 34h call and save the pointer for later use. For some 
unexplained reason, DOS versions 3.1 and above return a pointer to one byte 
past this IN_DOS flag byte to a critical error flag byte. The IN_DOSor DOS_CRITICAL 
function is summarized by 
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Entry: AH = 34h 
int 21h 
Returns: in ES:BX, a pointer to an IN_DOS flag 


A second undocumented MS-DOS function supporting TSR programs is the 
Background Process function, INT 28H. There is one time that MS-DOS can safely 
be interrupted even when MS-DOS has been called (i.e., the IN_DOS flag is non- 
zero). If MS-DOS is waiting for keyboard input, the IN_pDOSis set to 1, but MS-DOS 
calls INT 28H continually while waiting. The MS-DOS PRINT utility appears to be 
the only MS-DOS program that currently uses this interrupt, which would imply 
that its express purpose was to allow background utilities like spoolers to func- 
tion. If a TSR program replaces INT 28H and monitors for calls to it, MS-DOS func- 
tions below Clear_keyboard_buffer (Function OCh) may be safely used. 


GET USER_PSP and SET USER_PSP Functions 


Two other undocumented calls are needed for TSRs for file handling using the 
newer calling conventions added with DOS 2.X and 3.X. These support full direc- 
tory paths and use file handles rather than the FCBs of DOS 1.X and CP/M. DOS 
stores the file handles being used in the PSP with other operating system infor- 
mation. This base page consists of 100h bytes of memory and also includes the 
command line given for executing the program, the first two filenames given on 
the command line converted to FCBs, and a default disk buffer address, Data 
Transfer Area (DTA), that overlays the command-line area. 

This pair of undocumented calls provides a way to get and set the PSP of a 
process in DOS. Before doing any file handling in a TSR, the current user PSP of 
an interrupted program would first be read from DOS and saved, and then the 
PSP of the TSR program would be set. The TSR would do any DOS file calls nec- 
essary. Finally, the TSR would restore the user PSP in DOS back to the inter- 
rupted process. In this way, the TSR would not affect the application programs 
files or operating system specific information. 


The GET USER_PsP function is summarized by: 
Entry: AH = 50h 


int 21h 


Returns: in BX, the current user-process PSP segment from DOS 


The SET USER_PSP function is summarized by: 


Entry: AH = 50h 
BX PSP segment to set in DOS 
int 21h 
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Under DOS 2.X, if FCBs were used for file handling, file information was not 
stored in the PSP. As long as only FCB file calls were made, the user's PSP was not 
required by TSR programs. However, under DOS 3.X, all file handling in DOS is 
converted internally to file handles. Therefore, these undocumented calls are 
required when operating under DOS 3.X for all file and device handling calls. 


A Simple Memory-Resident Program 
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Let’s make our discussion concrete by showing a TSR in action. The MS-DOS 
GRAPHICS utility is an example of a very simple TSR program. Upon invocation, 
GRAPHICS tests to make sure that it was not previously installed. This is done by 
getting the current INT 5 Print Screen vector and comparing a number of bytes 
of the current handler with the corresponding bytes in GRAPHICS. Once we know 
that GRAPHICS isn’t there, our new INT 5 vector is installed pointing to GRAPHICS 
resident code. Now, the code in GRAPHICS will be executed when an INT 5 is in- 
voked (such as by holding down the shift and Print Screen keys). Additionally, 
GRAPHICS frees up some memory for use of other programs. MS-DOS loads com 
programs at 100h, and the memory area in the base page (0 to Offh) from 0 to Sch 
must be preserved for termination. GRAPHICS goes to the trouble of relocating 
the resident interrupt handler from 100h down to 60h in the PSP to save 160 
bytes of memory. (See Essays 6 and 10 for detailed discussion of the PSP and how 
it is used.) 


Basic Structure of TSRs 


Let's illustrate some of the ideas used in GRAPHICS with a simple TSR which al- 
lows disabling and enabling the Print Screen key. The basic structure of a TSR 
program usually consists of two parts: the resident code and the initialization 
and install routine. 

Since we would like to use as little memory as possible, the resident code is 
normally at the beginning of our program and the initialization code placed at 
the end, so it may be discarded after use. Again to minimize memory use, TSR 
programs are often coded in assembly language. However, more sophisticated 
applications might combine assembly language for certain crucial interrupt rou- 
tines with code produced from a higher level language compiler. 

Here is a “skeleton” showing the basic structure of a TSR program: 


begin: jmp init sjump to our initialization routine 


new_intxs ..... sour resident TSR code 
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;end of resident code 


INite: =—«-_—« woe ed sour initialization and install code 
swhich will be discarded after use 


The IBM Print Screen Function 


Depending on one’s perspective, the Print Screen is either a wonderful or a hor- 
rible feature. The ROM BIOS keyboard interrupt scans for keystrokes, and if the 
Shift key and the Print Screen key are held down at the same time, the keyboard 
handler calls a Print Screen function, software Interrupt 5. This is just fine if you 
hit those keys on purpose, but that Print Screen key is mighty close to the tiny 
Return key on the old-style IBM PC keyboard. Let's say it was an accident, and 
hope you have a printer connected and turned on, because that thoughtful Print 
Screen routine will wait nearly forever. If no printer is at hand, you can always 
reboot the machine and lose the last 30 minutes of the report you've been pre- 
paring. With a printer, we only have to turn it on and wait however long it takes 
to print out the screen. If we are in the middle of printing in WordStar or 
WordPerfect, of course, our printer gets a bunch of gibberish, too. It's clear that 
it would be useful to disable Print Screen, except for the few times we might 
really want it. But if we do want a screen dump, we want to be able to reactivate 
the Print Screen key. Thus, making our Print Screen toggle a TSR is appropriate. 


The PSOFF Program 


The program PsoFF enables or disables the built-in Print Screen routine. It was 
written for assembly into a small MS-DOS comfile. The program was written as a 
memory-resident procedure, which you might install using a batch file. For ex- 
ample, an AUTOEXEC.BAT file might contain the following for a serial printer: 


mode com1:9600,8,1,p 
mode lLpt1:=com1 
psoff off 


This would set up a serial printer as COM1 and disable the Print Screen 
function on bootup. At any time, PSOFF may be invoked with either the ON or OFF 
option to disable or enable the Print Screen function. For example: 


A>psoff on 
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would enable this function at some later time. 


How It Works 


The default Print Screen function is set up when the IBM PC ROM BIOS boots up. 
The ROM BIOS installs the routine as Interrupt vector 5. Our own PSOFF will be 
loaded into memory and will install a replacement routine at this interrupt vec- 
tor and stay resident. When PsoFF is invoked, the ON/OFF parameter will be 
scanned to determine whether Print Screen will be turned on or off. Once in- 
stalled, if we invoke PSOFF again, the program must check to see whether it is 
already installed in memory. If it's already there, the program just changes the 
ON/OFF setting as specified and exits without staying resident. If the proper ON/ 
OFF parameter is not found, like any good program PSOFF gives a help message 
describing its use and merely exits. 

PSOFF has two basic parts, the initialization code and the interrupt handler 
itself. In this simple example, almost all of the code is for initialization. The inter- 
rupt handler at NEWINTS is only six bytes long. It has two modes, either on or off. 
When Print Screen is OFF, the interrupt handler consists of a single IRETinstruc- 
tion (return from interrupt) to complete the function, bypassing the IBM PC 
Print Screen interrupt handler. When Print Screen is ON, the IRET is replaced 
with a NOP (no operation) followed by a JMP FAR instruction to the original inter- 
rupt handler. The memory resident part of this routine is about 40 bytes long. 

The initialization code will be used once and then discarded. It starts at the 
label INIT. The INIT routine goes through a series of small inline routines. You 
might note that conditional assembly was used so that slightly different versions 
could be created for either MS-DOS or CP/M-86. This technique can also be used 
to accommodate differences in MS-DOS versions if necessary. 

Table 7-2 lists a summary of the initialization routines used by PSOFF. Table 
7-3 lists subroutines. 


Table 7-2. Inline Initialization Routines 


Routine Operation 

init Set up segment registers and local stack 

getparm Test if proper parameters were given on command line 

movint If good parameters, copy pointer to existing Print Screen func- 
tion to our own code 

testint Test that PSOFF is not already installed 

change If PSOFF already installed, change its ON/OFF toggle, tell the 
user, and exit 

stint If PSOFF not installed, install our new INT 5 vector, tell user 


current status, exit, and stay resident 
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Table 7-3. PSOFF Subroutines 


Subroutine Operation 

bdos Call DOS (works with both MS-DOS and CP/M-86) 
pchar Print a single CHAR to the screen 

pmess Print a string terminated by a binary 0 to the screen 
crif Send a carriage return and linefeed to the screen 
saystat Tell user status of Print Screen function 


Here is Listing 7-1, PSOFF. You should be able to follow it by reviewing the 
preceding discussion and noting the comments. 


Listing 7-1. PSOFF 


TITLE ‘Print Screen Off Routine for MSDOS 4-3-85' 
pagewidth 96 


Print Screen Off Routine for MSDOS 
Author: M. Steven Baker 
Revision date March 25, 1985 
Last revision April 3, 1985 


Make using the following commands: 
MASM PSOFF; 

LINK PSOFF; 

EXE2BIN PSOFF.EXE PSOFF.COM 

DEL PSOFF.EXE 


Purpose: 
installs and stays resident in DOS to revector 
the print screen routine to an innocuous IRET 
when invoked with OFF parameter 


Operation: 
This program must be run first to disable the 
standard Print Screen Routine for PC-DOS. 
It revectors the INTS to this new code. 
This code stays resident until rebooting 
to allow a user to either turn ON or OFF 
the print screen routine. 


=e =e =e me os =e =e me =e =s =e =e =e me =e =e =e =e me =e ee me =e me me =e 


EQUATES 
continued 
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cr equ Odh 

lf equ Oah 

? 

false equ 0 

true equ not false 

r 

cpm86 = equ false 

msdos equ not cpm86 

? 

MASM equ true susing Microsoft or compatible 


;assembler 
ASM86 = equ not MASM~ ;using Digital Research 


if MASM suse some macros 
cseg macro 

CODE segment 

assume cs:CODE,ds:CODE,ss:CODE 


endm 
jmps macro dummy ;jump short macro 

jmp short dummy 

endm 
rs macro count sreserve storage 

db count dup(?) 

endm 

endif ;MASM 
fcb equ OSch sfile control block for parameters 

cseg 

ORG 0100h 
; 
; Sign on message 
; 
begin: jmp init sjump to initialization code 

jmp newint5 ;jump to our new interrupt code 
; 
vernm db ‘Print Screen On/Off Version 1.0 4-3-85',0 
; 
continued 
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newintS db 90h sNOP space for our IRET 
db Oeah sjump far instruction 
ints dw 0,0 skluge jmpf entry point 


ssince MASM won't assemble a 
sjump far instruction 


INIT 
initialization code for installing our interrupt 


ade MO =e =e =e 


nit: mov ax,cs ssetup segment registers 
mov ds,ax 
mov es, ax 
mov S$$,ax 
MOV SP,Offset stack 
; 
CALL crlf 


test if proper parameters are there 


getparn: 
mov si, fcb+1 
mov al, Csi] 
cmp al,’ ' 
jne testparm ;if no parameters, then give help 
help: jmp givehelp 
: 
testparm: 
mov di,offset on_stg ;point to ON string 
mov cx,4 scompare four bytes 
tparmi: cmpsb scomparison 
jne tparm2 
Loop tparm1 
mov byte ptr newint5,90h ;put NOP at newintS 
jmps movint 
; 
tparm2: mov si, fcb+1 ;point to parameter 
mov di,offset off_stg ;point to OFF string 
mov cx,4 scompare 4 bytes 
tparm3: cmpsb ;compare them 
jne help 
Loop tparm3 
mov byte ptr newint5,Ocfh ;put IRET opcode at newint5 


=e 


continued ° 
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; copy print screen interrupt vector to our JUMP FAR return 
; used to return from our checking code 
; 


movint: xor ax, ax szero AX 
mov ds,ax sset DS to segment 0 
cld sset forward direction 
mov $i1,14h ;pointer to int5S 
mov di,offset int5 ;pointer to our JUMP FAR code 
mov ax,cs 
mov es ,ax ;set ES to our code segment 
movsw smove offset 
movsw ;move segment 


now test that we have not already previously installed this 
at the print screen interrupt 


=e =e 6&8 Ue 


testint: 
mov si,14h ;pointer to int5 
Lodsw sget offset to AX 
mov dx,ax ;save offset to DX 
lodsw sget segment to AX 
mov es, ax ;temporarily store it in ES 
mov ax,cs srestore our DS register 
mov ds,ax 
mov ax,offset newintS 
cmp ax,dx soffsets are not equal 
jne setint 
: 
mov si,offset vernm ;point to version name 
mov di,si sin both SI and DI 
mov cx, (offset newint5)-Coffset vernm) 
testint2: 
cmpsb ;compare them for equal 
jne setint 


Loop testint2 


change: 
mov si,offset newint5S 
mov di,si 
movsb sand CHANGE it 
call saystat sgive user current status 
jmp exit 
; 
continued 
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now replace INT5 interrupt vector with pointer to our code 


setint: mov 


me 


mov 
mov 
xor 
mov 
mov 


cld 
cli 


mov 
stosw 
mov 

stosw 


inton: sti 


e 


mov 
mov 


call 


done: 


me =e we 


if 

exit and stay 
mov 
mov 
call 
endi f 


if 
terminate but 

mov 

int 

endif 


ax,cs 

ds, ax ssetup DS cs 

bx, ax ssave our code segment in BX 
ax, ax ;zero AX 

es,ax ssetup ES as segment O 
di,14h spoint to INTS vector 


sset forward direction 
sshut hardware interrupts off 


ax, offset newint5 ssetup our int5 


ax, bx snow set our code segment 
sand store it 


sturn back on interrupts 
svector has now been replaced 


ax,cs 
ds,ax 


saystat stell them status 


cpm86 

resident under CPM86 
cl,0 ssetup for exit 
dl,1 sstay resident 
bdos 


msdos 

stay resident under dos 
dx, Coffset init)+1 

27h 


exit but don't stay resident 


givehelp: 


continued 
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mov si,offset helpmsg sgive help message 
call pmess 
sand fall thru to exit 
exit: 
mov ax,0 
mov dx ,ax sset DX =0 for CPM86 exit 
call bdos 
; 
; SAYSTATUS 
H Say status of Print Screen Function 
H ENTRY none 
; EXIT AX and SI are destroyed 
: 
Saystat: 
mov si,offset endmsg ;tell them we're done 
call pmess 
mov al,byte ptr newintS ;get value either NOP or IRET 
mov si,offset onmess 
cmp al,90h 
je saystat_2 
; 
mov si,offset offmess 
cmp al,Ocfh 
je saystat_2 
mov si,offset badmsg 
Saystat_2: 
call pmess 
call crlf 
ret 


DOS interface 


’ 
7 
: 
c 


rlf: push ax 
mov al,er 
call pchar 
mov al, lf 
call pchar 
pop ax 
ret 

: 

pchar: push ax 
push bx 
push dx 


continued 
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mov dl,al 
MOV ah,2 
call bdos 
pop dx 
pop bx 
pop ax 
RET 

PMESS 


print message to screen 
Entry SI = pointer to message terminated by null byte 
Exit AL and SI destroyed 


me =e me a6 me 


pmess: lodsb sget byte 
or al,al sis it zero?? 
jnz pmess2 
ret 
pmess2: push si ssave pointer 
call pchar ssend character 
pop si srestore pointer 
jmps pmess sand continue 
bdos: 
if cpm8&6 
push es spreserve ES 
push cx ssave CX 
mov cl,ah sfor cpm8&6 
int OeOh 
pop cx srestore registers 
pop es 
endif 
; 
if msdos 
int 21h 
endif 
ret 
; 
datast equ $ 
DSEG 
org offset datast 


message texts 


me =e =e 


helpmsg db ‘USAGE as follows:',cr,lf 
continued 
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db ' A>PSCREEN ON (to ENABLE print screen function) ' 
db cr, lf 
db ' A>PSCREEN OFF (to DISABLE print screen function) ' 
db cr, lf,0 

; 

endmsg db ‘Print Screen Function is ',0 

onmess' db "ENABLED - ' 

on_stgdb ‘ON =§',0 

offmess db ‘DISABLED - ' 


off_stgdb ‘OFF ',0 


8 


badmsg db ‘xx CORRUPTED OR DAMAGED xxx! 
DB cr, lf, ‘PLEASE REBOOT SYSTEM’ 
db cr, lf,0 

? 

; 

RS 100h 

Stack dw 0 

intend equ $ 
if MASM 
CODE ends 
end begin 
endif 
if CPM86 
end 
endif 

A Closer Look at TSRs 
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Now that we've seen in detail how a simple TSR is implemented, let's look at some 
more complex examples by examining the MS-DOS ASSIGN and PRINT programs 
more closely. 


The ASSIGN Command 


The MS-DOS AssI6N utility is an example of a more complex TSR program, 
which modifies MS-DOS itself but does not make any MS-DOS calls when resi- 
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dent. This utility allows the user to assign any logical drive (from A-H in DOS 2.0) 
to any actual physical drive. Its main purpose is allowing those poorly written 
programs that absolutely expect their data files to be on drive “B” to run on a 
hard disk machine. ASS16N does this logical-to-actual drive mapping by replacing 
a number of software interrupts, as shown in Table 7-4. 


Table 7-4. Interrupt Vectors Replaced by ASSIGN 


Interrupt Function 

INT 21h Dosint Patches the filespec and disk drive string passed on to the 
original MS-DOS interrupt 

INT 25h Absolute Disk Read _ Patches drive number in AL, then passes on to original in- 
terrupt vector 


INT 26h Absolute Disk Write Patches drive number in AL, then passes on to original in- 
terrupt vector 

INT 2Fh Multiplex Interrupt Provides a way to communicate with the resident part of 
the ASSIGN program (only replaced in versions distrib- 
uted with DOS 3.X) 


The Diskette __IO (INT 13H) interrupt is not modified, so calls to the ROM 
BIOS will not be affected by this utility. The memory-resident part of ASSIGN 
maintains a simple table of 8 bytes that map to actual disk drives. When a drive is 
assigned, the value in this table is changed to reflect the actual drive to be used 
as this logical disk. When the ASSIGNcommand is given without parameters, the 
default logical to physical drive table is copied into the memory-resident code, as 
follows: 


disktabl db 1,2,3,4,5,6,7,8 sdefault disk assign table, 
sie, Logical drive A = disk 1 


Complex TSR Programs That Make MS-DOS Function 
Calls 


These applications include the more complex TSRs that, once resident, must 
make MS-DOS function calls used for file reading and writing. Such programs 
must be much more carefully written to be certain that they interrupt MS-DOS 
operations and other activities only when it is safe to do so. Some of the hard- 
ware interrupts such as the keyboard or timer may be replaced by the TSR. To 
do this properly requires a greater understanding of the hardware controller 
(Intel 8259 chip), various machine specific hardware features and the internals 
of the IBM PC ROM BIOS code. 
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PRINT: A Model Memory-Resident Program 


The MS-DOS PRINT utility can be considered to be a model TSR program. It is a 
good example in that it uses both documented and undocumented TSR functions 
in MS-DOS. It also must make MS-DOS calls after becoming memory -resident so it 
can read disk files and print them in the background. Two hooks are used for 
background printing, the Background Process INT 28H (MS-DOS software inter- 
rupt) and the Timer _tick INT 1CH (a ROM BIOS software interrupt). These two 
interrupts are vectored to the resident part of PRINT which then tests several 
other monitors to make certain that MS-DOS is interruptible. These other flags 
include whether Diskette__IO is in process or the IN_0OS flag is set (i.e., an MS- 
DOS call was already in process). The following is a rough list of the initialization 
routine for a TSR (such as the MS-DOS prRInT utility) that must make MS-DOS calls: 


. Test for DOS Version above 2.0 since you will be using some undocu- 


mented features not available in MS-DOS 1.X. If not okay, exit. 


. Check to see whether the resident part of PRINT has previously been in- 


stalled using Multiplex INT 2FH call with AH = 1and AL = 0 et in- 
stalled state). If PRINT already installed, the remaining initialization steps 
are not executed. 


3. Free memory allocated to the environment for the PRINT program. 


aN 


oN OD OH 


10. 


11. 


12. 
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. For the PRINT spooler, open the appropriate list device to make certain 


that it exists. 


. Save old Background INT 28H and install your own. 

. Save old Multiplex INT 2FH and install your own. 

. Save old Diskette_IO INT 13H and install your own. 

. Save existing Printer_IO INT 17H, RS232_IO INT 14H, and Print__Screen 


INT 5 interrupt vectors and install your own. These replacement inter- 
rupt routines will return printer busy if another application tries to 
print while you are spooling a file to printer. 


. Call IN_bOs function (INT21H Function AH = 34h) and save pointer to the 


DOS_CRITICAL byte in DOS. 


Save old Bootstrap INT 19H vector and install your own. This step was only 
added in DOS 3.3 PRINT. A call to your new INT 19H will restore all the old 
ROM BIOS vectors and invoke the original INT 191—reboot the system. 


Save old Timer _Tick INT 1CH and install new vector. This step is omitted if 
a NETBIOS interface has already been installed. 


Set DX pointer to end of resident part of PRINT code, and terminate and 
Stay resident. 
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When the resident part of PRINT is invoked by one of the two hooks, it 
checks to make certain that INT 13H (Diskette__IO) was not in progress). Disk op- 
erations cannot be interrupted, so if Diskette_IO is occurring, PRINT will re- 
turn-control to the current application. If entry was by INT 1CH (Timer _Tick), it 
also checks the IN_DOSs flag to make certain a critical MS-DOS function is not 
being interrupted. The Timer _Tick interrupt is called during each hardware 
timer tick (18.2 times a second). The INT 1CH entry also sends an End of Interrupt 
(EOI) command to the interrupt controller chip (Intel 8259) so that other hard- 
ware interrupts can occur. If other hardware interrupts are pending, then PRINT 
returns without printing a character. 

PRINT is also careful about saving and restoring certain other parameters 
before invoking MS-DOS calls which might return an error such as reading a file. 
If a hardware error occurs, it must be caught by PRINT, not passed on to the 
interrupted application. The resident part of PRINT has a 512-byte buffer (DOS 
2.X) for reading files to spool from disk. MS-DOS version 3.X allows the user the 
ability to increase this buffer size. The following is a rough list of what is done 
before and after a file open, disk read, and file close to protect an application 
program from errors. 


. Save old user PSP segment. 

. Save old INT 24H Critical Error Handler. 

. Save old DTA. 

. Install your own INT 24H vector (Error Handler) to catch any errors. 
. Set DTA to your disk buffer address, set to your PSP in DOS. 

. Make DOS call for disk read. 

. Restore old DTA. 

. Restore old INT 24H Critical Error Handler. 

. Restore old user PSP in DOS. 


oon a ff Ww Kw 


An UNSPOOL TSR Program 


To illustrate some of these considerations, we will outline the structure of a TSR 
utility to capture output to the printer device and write it to a file. (For space 
reasons, we cannot include a complete listing.) This program will also incorpo- 
rate a “hot key” feature to turn on or off this feature at any time. The hot key 
feature will save the screen and bring up a popup menu. The hot keys could also 
allow you to change the name of the unspooled file from a default name. After 
this menu use, we will restore the screen to its condition before the TSR activa- 
tion. 
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The basic structure of our program UNSPOOL will be similar to what we have 
seen already. However, the amount of coding for the resident and initialization 
parts of the TSR will be much larger. Here is the outline: 


jmp init sour initialization code 
jmp newint17 sour replacement Printer_IO 
db ‘UNSPOOL Version 1.3 2-20-87',0 

: 

newint17: 


peaterers sresident code ends 


init: sour initialization and 
sinstall routines 


re eee 3;TSR ends 


UNSPOOL Program Structure 


Table 7-5 shows the interrupts that we will need to intercept for this TSR. In 
addition, just before doing any MS-DOS file operations, we will need to save the 
current DOS user PSP and install our own PSP segment in DOS. Next, we tempo- 
rarily replace INT 24H to protect and intercept any errors and replace the default 
DTA—the buffer into which DOS will read the file. After MS-DOS file operations, 
the original INT 24H handler, the application PSP, and DTA must be restored. 


Table 7-5. Interrupts used by UNSPOOL 
SS a a I SRY I He) 
Interrupt Function 


5 Print Screen interrupt, need to disable if unspooling taking place 
9 Keyboard hardware interrupt, sets flag for activation by “hot keys’ 
13h Diskette __IO, monitors disk routine to prevent trashing 

Wh RS232_1IO, for serial printer output 

15h Cassette _10, determines if UNSPOOL is already memory-resident 
16h Keyboard _IO, watches for a particular character sequence 

17h Printer _IO, for parallel printer output 

1Ch Timer _Tick, vector interrupt for activation 

28h Background Interrupt, vector DOS interrupt for activation 

2Fh Multiplex, monitors calls to printer multiplex 


Before bringing up any popup menu, we will need to save the current 
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screen and state of other video parameters. This will require space in the resi- 
dent part of our TSR for storage of the video parameters and the screen. Then 
we can bring up our menu and get keyboard input from the user. Finally, the 
screen will need to be restored along with any video parameters. 


Programming Guidelines for TSR Programs 


You should now understand the basic procedures for writing various kinds of 
TSRs. Microsoft has provided a draft specification for TSR programs to develop- 
ers (Andrews 1986). These draft guidelines define a set of operational rules for 
TSR programs to minimize conflict when other memory-resident utilities are 
loaded. They do not document or describe the undocumented features of DOS 
which TSR implementers must know. The gist of the suggestions are that TSR 
programs should mimic MS-DOS and the ROM BIOS as much as possible. Some 
valuable basic guidelines are found in the following areas: general issues, the 
keyboard, video issues, and TSR program interface. 


General Issues 


You should design your TSR program s0 it can easily coexist with other TSR pro- 
grams in memory. It should not be critical that your program be the last inter- 
rupt vector in the chain of interrupts. Setting up a local stack in an interrupt 
routine of your TSR program prevents it from being reentrant. If the interrupt is 
invoked again, the earlier local stack contents will be written over. Use a local 
stack only when needed and hardware interrupts are off, or in an area pro- 
tected from reentry. When using your own MS-DOS Critical Error Handler, do 
not jump from it to your TSR program code. Instead, set a global error flag that 
your TSR routines check, issue an IGNORE response in the error handler, and 
return to DOS (using an IRET instruction). This assures that the MS-DOS stacks 
will be cleared properly. 


Keyboard Issues 


Don’t take complete control of INT 9 (hardware keyboard interrupt). If your TSR 
program wants to use keystrokes that the IBM PC ROM BIOS doesn’t generate 
(i.e., the CTRL-UP arrow key is not decoded by the original PC or AT ROM BIOS), 
install your routine, chain into the interrupt, generate a new scan code, and put 
it into the IBM PC keyboard buffer just as the ROM BIOS does. If you are looking 
for a single keystroke, set a flag and continue through the interrupt. When the 
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TSR is running, it should use INT 16H (ROM BIOS Keyboard __IO routine) to get a 
keyboard input. This allows all TSRs in the chain to see the key request and take 
any appropriate action. 


Video Issues 


Use the ROM BIOS whenever possible. If you directly change video modes, cur- 
sor types, background intensity, EGA, or VGA registers, save the new values in 
the appropriate ROM BIOS and video data areas. 


TSR Program Interface 


This draft guideline also proposes an extensive format of data records for TSR 
programs and a program interface. The program interface proposed would use 
Cassette_IO INT 15H (Function AH = 52h) as a method for the nonresident parts 
of programs to communicate with resident parts. Unfortunately, this TSR format 
has not been widely implemented and may never be. 


The Bottom Line 


As a programmer, do I use memory-resident programs myself? Only in special 
situations. I want as little to interfere with my programming and testing as possi- 
ble. Oh, I wouldn’t mind a good screen-capture utility now and then. But most 
users do appear to like TSRs and that's a driving force for software development. 
From my perspective, TSRs do serve a useful purpose when modifying hard- 
ware or ROM BIOS routines. I personally prefer to use “program loaders,’ small 
programs that load another application and change the MS-DOS or hardware 
environment. Then, when the application is done, they disappear and go away. 
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Data Protection and 
Encryption 
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Asael Dror 


Cssipite? data security is becoming a critical problem, especially with 
microcomputers. Though it is rarely admitted, a survey reported in PC WEEK 
(June 9, 1987) suggests that more than 80 percent of corporations and agencies 
have suffered financial loss due to computer security problems. 

The same factors which have helped create the microcomputer revolution 
have also contributed to the data security problem. The availability of inexpen- 
sive microcomputers encouraged small businesses and individuals, who had 
never used computers before, to adopt microcomputers. Meanwhile, in large 
businesses the concept of data distribution—placing the data close to the user— 
has caused the transfer of information from the traditional mainframes to 
microcomputers. These trends have been further magnified by technological 
advances such as fast communication devices, large capacity hard disks, and 
LANs, which make it easier to transfer, store, and retrieve large amounts of data 
on microcomputers. Finally, a dramatic increase in computer literacy has given 
more people the knowledge needed to access the data. Thus, having easy access 
to large amounts of (often sensitive) data has greatly increased the means and 
opportunities for such computer security problems as illegal access, data tamp- 
ering, and computer vandalism. 


Three Levels of Unauthorized Data Access 


What does illegal data access involve? Unauthorized data access can be classified 
into three levels. In order of increasing potential for damage, they are 


& Deletion 
f= Reading 
i Changing 
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Deletion 


Deletion of data is (surprisingly) the least harmful of the three levels of unau- 
thorized access. Detecting a major deletion is simple—your data is gone. (If the 
deletion is such that it is not immediately evident, we shall view it as a change to 
the data rather than deletion.) All that has to be done to recover from deletion is 
to restore the data. This is an easy matter, assuming you have a recent backup 
locked away. The only harm caused by the illegal access is that you lose whatever 
data had been entered since your last backup. 


Reading 


When people talk about violations of data security, they are most often referring 
to reading your data. An unauthorized person who wants to read large amounts 
of your data needs to access your computer for only enough time to copy your 
hard disk onto diskettes to be read later at leisure. Since reading leaves no 
marks, you cannot detect the unauthorized access and so will not take measures 
to minimize the damage. 


Changing 


The most severe data access violation is changing your data. Someone not only 
reads your sensitive data but also falsifies it undetectably. While the intruder 
now has the correct data, you are using a maliciously falsified version. This can 
cause considerable damage not only to obviously sensitive data but also in lesser 
areas. Very small changes in the data can make big differences: credit becomes 
debit, $10 becomes $10 million, a “D” grade becomes an “A?” research results be- 
come false, the number of your safety deposit box is altered, key people are 
moved around, and so forth. 


Multilayer Protection 
To protect data, a three-layer system should be used: 


1. Physical security: limiting access to your computer, keeping your back- 
ups secured, destroying printed reports, etc. 


2. People confidence: ensuring reliability of people who are authorized to 
access the data 


3. Data security: protecting your data on the computer from unauthorized 
access by someone who has bypassed the physical security 
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This paper will deal only with the third issue, i.e., the technical means for secur- 
ing data on MS-DOS machines, but remember that all three elements are impor- 
tant for protecting your data. 


MS-DOS Data Structure and Access 


Before we can protect the data, let’s review how data is organized and accessed 
in the MS-DOS environment. When DOS allocates and frees disk storage space, it 
does so in chunks of sectors called clusters. A cluster is a fixed number of consec- 
utive sectors the size of which is determined at the time the media is formatted 
by DOS. For example, when using DOS 3.X with a hard disk of 30MB, a 4-sector 
(2K) cluster will be used. Space is allocated and deallocated by MS-DOS as 
needed. When a file grows, more clusters are allocated for it and when the file 
shrinks, clusters are deallocated. 

MS-DOS “sees” a file as an ordered sequence of clusters. The order of the 
file's clusters is kept in the File Allocation Table (FAT). Other information about 
the file, such as its name and attributes, are kept in a directory. 


Directories 


A directory is a collection of entries describing files. There are two types of di- 
rectories: the root directory is a special area of fixed size and location, and the 
subdirectory is a DOS file having the subdirectory attribute. Each directory en- 
try is 32 bytes long (see Figure 8-1) and has the format shown in Table 8-1. 


Indicate Attributes First 
empty entry Cluster 


Fig. 8-1. Directory entry. 


The FAT is a collection of entries, each describing one cluster. A FAT entry 
for a cluster which is allocated to a file has the number of the subsequent cluster 
of that file. So, to find the chain of clusters making up a file, we find the first 
cluster in the file’s directory entry and then follow the chain. Each cluster’s entry 
in the FAT will tell us what the next cluster of the file is. 
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Table 8-1. Directory Entry Format 


Byte Length 

offset in bytes 

(decimal) (decimal) Description 

6) 8 Filename (without the extension) or an indication that this en- 
try is empty 

8 3 Filename extension 

11 1 The file's attribute (This is a bit field in which the individual 


bits are used to indicate that the file has particular attributes: 
01H = READ ONLY, 02H = HIDDEN; 04H = SYSTEM FILE; 
08H = VOLUME LABEL; 10H = SUBDIRECTORY; 20H = AR- 
CHIVE; 40H and 80H = Reserved, always 0.) 


12 10 Reserved 

22 2 The time this file was last updated 
24 2 The date this file was last updated 
26 2 The file's first cluster 

28 4 The file's size 


Accessing the Data 


The MS-DOS data access system is designed as a layered architecture with the 
following layers: the application program, MS-DOS, BIOS, and the computer's 
hardware. Each layer has its own “vision” of how the data looks and uses the 
services of the adjoining (deeper) layer for accessing the data. This design helps 
to disconnect the higher layers from the hardware implementation details and 
thus achieve hardware independence. 

Application programs use the services of DOS to access the data by per- 
forming software Interrupt 21h and passing the required parameters. When 
DOS is called on to perform data access operations, reference to the data is made 
by filename and the relative offset of the data within the file. Some common 
MS-DOS data-handling functions accessed through Interrupt 21h include: open 
a file function 3Dh), close a file (Function 3Eh), read from a file (Function 3Fh), 
write to a file (Function 40h), delete a file (Function 41h), and move the read/ 
write pointer in the file (Function 42h). 

The next layer, DOS, uses the services of BIOS to access the data. BIOS is 
DOS's interface to the computer's hardware. The call to BIOS is performed via 
software Interrupt 13h passing the required parameters. When calling BIOS, 
reference to the data is not made by files, which BIOS does not understand, but 
by the physical location of the data, i.e., the device, head, track, and sector num- 
ber. Two of the data-handling functions that BIOS provides are: read a sector 
(Function 02) and write a sector (Function 03). 

The innermost software level, BIOS, communicates directly with the hard- 
ware (disk, DMA, timer, and interrupt controllers) via input and output instruc- 
tions. (See Essay 1, A Guided Tour inside MS-DOS, by Harry Henderson, for 
further discussion of the three layers of MS-DOS.) 
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Hiding Your Data 


A simple strategy to protect your data is to hide it. If no one knows you have the 
data or where the data is kept, it cannot be accessed. 


Hiding Data with Nonstandard Filenames 


One way to hide data is to use nonstandard filenames. MS-DOS specifies that file 
and subdirectory names may use only the following characters: A-Z 0-9$#& @ 
%()-{}°_. 

In practice, many other nonstandard characters may be used. Some of 
them cannot be typed directly from the keyboard but may be entered by holding 
down the ALT key, pressing the character's ASCII code on the numeric keyboard, 
and then releasing the ALT key. For our purpose, the most useful of those non- 
standard characters is the null character (which has ASCII code 255). This char- 
acter appears on the screen as a blank and can be used to create invisible file and 
subdirectory names such as <null><null>.<nullt>. To access such a file, one 
must use the exact filename: <null><null> is a different filename from 
<nul l><null>.<nuLll>. It is possible to create 32 different filenames using only 
this character, but, of course, you too must remember the exact name yourself. 


‘Hiding with Hidden Files 


Another way to hide your data is to create an MS-DOS hidden file. A file or sub- 
directory that has the HIDDEN attribute in its directory entry on, will not be listed 
by the DIRcommand. This is the technique used to make the PC-DOS system files 
IBMDOS.COM and IBM8I0.COM invisible. Note that the MS-DOS ATTRI8 command 
which can change some of the attributes of a file does not support changing the 
HIDDEN attribute. 

Listing 8-1 is a program named HIDE that toggles the HIDDEN attribute of a 
file or subdirectory, that is, it makes a visible file hidden and vice versa. The 
program reads the current attribute of the file, changes the hidden attribute bit 
and rewrites the attribute. Note that the program clears the suB DIR attribute. 
This is done since Function 43h of Interrupt 21h cannot be used to set (or reset) 
the sus OIR attribute. 


Listing 8-1. HIDE 


title ‘hide’ 


; This program toggles the hidden attribute of a 
3; file or subdirectory, 
continued 
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thus making a visible file hidden or a 
hidden one visible 


@e os 


Usage: HIDE filename | subdirectoryname 


me 


Written by Asael Dror July 1987 


me 


The sequence to generate hide.com is: 
masm hide; 

Link hide; 

exe2bin hide.exe hide.com 


A eT et ee 


HIDE_ATTR EQU O2h ; HIDDEN file attribute 
SUB_DIR_ATTR EQU 10h ; SUB. DIR. file attribute 
SPACE EQqu ' ' 


onlyseg segment 


PARAMLN) equ 80h 
org 100h ; for .com file 
hide proc far 


assume cs:onlyseg,ds:onlyseg,es:onlyseg 


cld 

mov di,PARAMLN 

sub ch,ch 

mov cl,byte ptrldi] 3; get arg len. 
jexz fail ; No arg. given 
inc di : di -> arg. 

mov al, SPACE 

rep scasb ; scan for first nonblank 
je fail : no arg. (filename) given 
inc cx ; adjust length and pointer 
dec di 

mov si,offset filenm 


continued 
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xchg si,di ; si->arg. di->filenm 
rep movsb ; save arg. as filenm 


mov dx,offset filenm 

mov ax, 4300h 

int 21h ; get file's attribute 

je fail 

xor cl,HIDE_ATTR ; toggle HIDDEN attr. 


s leave SUB DIR ATTR 


:; along 

and cl, (NOT SUB_DIR_ATTR) 

mov ax, 430th 

int 2th s set file's attribute 

jc fail 

mov ax, 4cO0h 

int 21h ; terminate, errorlevel=0 
fail: 

mov dx,offset failmsg 

mov ah,O9h 

int 2th s print fail message 

mov ax ,4c08h 

int 2th ; terminate, errorlevel=8 
filenm db 64 dup (0) ; space for the file name 


failmsg db ‘Cannot change hidden attribute $' 


hide endp 
onlyseg ends 
end hide 


Protecting data by hiding files may be an effective strategy against a casual 
observer who uses the DIR command. However, special directory-listing pro- 
grams (as well as the DOS CHKOSK/V command which lists the tree structure of 
the entire disk including all hidden files) are able to reveal such hidden files. 
Here are the results of using HIDE program. The directory as it is shown by the 
DIR Command: 


Volume in drive D is VDISK V3.3 
Directory of D:\ 
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FOO 9 8-19-87 11:40a 
HIDE COM 162 8-19-87 10:07a 
2 File(s) 386048 bytes free 


The directory as it is shown by the DIR command after HIDE FOO was used: 


Volume in drive D is VDISK V3.3 
Directory of D:\ 


HIDE COM 162 8-19-87 10:07a 
1 File(s) 386048 bytes free 


CHKDSK/V still shows the hidden file Foo: 


Volume VDISK V3.3 created Dec 6, 1984 12:00p 
Directory D:\ 

D:\VDISK V.3.3 

D:\FOO 

D: \HIDE.COM 


387072 bytes total disk space 
512 bytes in 2 hidden files 
512 bytes in 1 user files 

386048 bytes available on disk 


655360 bytes total memory 
567984 bytes free 


but DEL FOO will give a File not found when the file is hidden. Entering HIDE Fo0a 
second time cancels the file’s HIDDEN attribute and makes it appear in the DIR 
listing and deletable by the DEL command. 


Protecting Files Using the Read-Only Attribute 
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MS-DOS provides a READ ONLY file attribute that means the file cannot be changed 
or deleted. The READ-ONLY attribute, like the HIDDEN attribute, is a bit field in the 
file's directory entry. The READ-ONLY attribute can be changed by using the DOS 
3.X ATTRIB command (or by writing a program similar to the one used to toggle 
the HIDDEN attribute bit). Unfortunately, protecting a file by making it READ-ONLY 
is really more a precaution against accidental access than a means against inten- 
tional malicious access, since the READ-ONLY attribute can be easily turned off 
and then the data deleted or changed. 
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Password Protection 


The next level of security is the use of password protection. We will build such a 
protection system starting with the simpler but less effective ways and then 
gradually improve it. Let's begin with a system that is supposed to protect the 
whole hard disk from access by unauthorized agents. Such a system should, at a 
bare minimum, require the user to enter a correct password before any access 
to the hard disk is allowed. 

The simplest (and least effective) way of doing this is by placing a small pro- 
gram in the AUTOEXEC file. This program would be activated when the computer is 
booted and would request the user to enter the correct password. If the correct 
password is entered, the program terminates normally and the system can be used. 
However, if the correct password is not given, the program would halt the computer 
(switch interrupts off and issue the HLT command to the CPU). Unfortunately, such 
a program can be bypassed easily. The AUTOEXEC is a batch file, and so can be termi- 
nated by pressing BREAK before our password program is even activated. 

We could improve this program, by making it immune to BREAK. This can 
be done by writing the program as a device driver instead of running it from the 
AUTOEXEC. If we do so, it becomes an extension of DOS and so it is impossible to 
prevent the program from running. Whenever DOS is booted from the hard 
disk, the password program will receive control. Since our program does not 
drive any device, which is what device drivers are really meant to do, we are 
actually writing a fictitious device driver that does all of its work in its initializa- 
tion routine. (See Essay 11, Writing a SOUND Device Driver, by Walter Dixon, for 
a detailed discussion of the structure and function of device drivers.) Now it 
seems that we have solved the problem. Whenever the system is booted our de- 
vice driver will “take control,’ prompt the user for the password and refuse ac- 
cess to the system if the correct password is not given. However, this protection 
system can be completely bypassed by booting off a diskette instead of the hard 
disk that contains our device driver. 

‘There are two different approaches to solving this problem: A simple hard- 
ware solution is to physically disable the ability to boot off a diskette. This can be 
done most easily by disconnecting the drive A: diskette. (The drive B: diskette can 
be left in place.) This solution has the following disadvantages: 


i> We cannot have two internal diskette drives. 


- Some programs access drive A: directly (such as some copy-protection 
systems) and so will not work (even if We use the ASSIGN command to 
substitute another drive for A:). 


‘> If our hard disk fails or we want to switch to a new operating system, we 
have to reconnect drive A:. 


> Jf an intruder can connect drive A:, the password system could be by- 
passed. 
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A second approach would be to move our password program from the DOS 
level to the BIOS level. We can develop an adaptor card which will have a CMOS chip 
with a battery backup for storing the password, and a program in ROM to prompt 
for the correct password. To have the password program receive control before 
DOS is booted, the ROM must be located on a 2K boundary in the address space 
C8000H through EOOOOH. Also, the ROM must have the following special signature: 
Byte 0: hex 55; Byte 1: hex AA; Byte 2: the length of our ROM in blocks of 512 bytes; 
Byte 3: the ROM’ entry point. A checksum is done to determine the integrity of the 
ROM. To be valid, the sum of the bytes in the ROM modula 100h has to be 0. 

During POST (the machine's Power On Self Test), the ROM will receive con- 
trol by a FAR CALL to its entry point. 

At last, we have a reasonable protection system. Alas, our system provides 
protection to our whole hard disk as one unit. We cannot limit different people 
to different types of access. We have a “go or stop” system: if you know the pass- 
word you can do everything, if you do not know it you can do nothing. Another 
limitation of this system is that once the password is given, the system is fully 
available to anyone. If you take a coffee break and do not turn the power off (or 
otherwise pass control to the password program), you leave your system totally 
vulnerable. Also, if the adaptor card can be pulled out, our protection system is 
not activated, and there is always the possibility of physically removing the hard 
disk and accessing it on a different computer. 


Password Protection of Selected Data 


Transforming a system from a whole disk protection system to a protection sys- 
tem for individual files or subdirectories giving different people different access 
privileges requires intercepting every attempt to access the disk. With a data- 
protection program that is always memory-resident (either a TSR, device driver, 
or added ROM, it is possible to redirect all hard disk access attempts to our rou- 
tine, which will then check for authorization. (See Essay 7, Safe Memory-Resi- 
dent Programming (TSR), by Steven Baker.) We can intercept access attempts to 
the hard disk either at the DOS or the BIOS level. 

To intercept at the DOS level, we have to reroute the DOS access Interrupt 
(21h) to point to our routine instead of to DOS. This is done by manipulating the 
interrupt vector for Interrupt 21h located at address 0:84h. Once the interrupt 
vector points at our interrupt-handling routine, every time a call is made to DOS, 
our routine will receive control instead. In the routine, we need to determine 
whether the function requested is a file access and, if so, check for authorization 
(i.e., the password check). Afterwards, we have to transfer control over to DOS to 
finish the work that was originally called for. Intercepting at the BIOS level does 
not give any significant advantages over intercepting at the DOS level and has 
many complications, so it is not recommended. 
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Data Encryption 


The major disadvantage of the password protection systems described above is 
that someone can bypass our intercepting routines, which can be done at least 
as easily as we intercepted DOS (or BIOS) by simply remanipulating the appropri- 
ate interrupt vectors. Furthermore, someone can remove the hard disk and read 
it on a different machine, giving full access to the data. 

The best solution to those problems is to move the protection level down to 
the data itself. After all, this is really what we want to protect! The most fool- 
proof way to protect the data itself is to scramble (or encrypt) it so that it be- 
comes incomprehensible to unauthorized persons. There are two basic 
procedures for encrypting data: code systems and cipher systems. 


Code Systems 


Code systems are based on using a code book to transform the data to its en- 
coded form. There are two basic code book systems: the dictionary type and the 
key tape type. 


Dictionary Systems 


Code book systems use a special kind of dictionary code book, to translate the 
original (plaintext) data to and from its encrypted form (ciphertext). Figure 8-2 
shows how a code book would be used to encrypt the message “secret message” 


Secret RVAHVX 
Message KVRRGTV 
Code Book 
Plaintext Ciphertext 


Fig. 8-2. Simple code book example. 


A code book can be devised that will encrypt bytes, letters, words, or 
phrases. The problem with using a code book is that our data is (usually) not a 
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collection of random information, so it has patterns that are passed on to the 
encrypted data. The presence of those patterns in the ciphertext gives the 
codebreaker a great starting point from which to decode the data. For example: 
the letter e is the most frequently used letter in the English alphabet. If our code 
book translates every occurrence of the letter e to d, the most frequent letter in 
our ciphertext will be d. When our ciphertext is analyzed, it will immediately be 
apparent that d is the most frequent letter, thus leading to the conclusion that it 
represents the letter e. This is a first step in decrypting our message. 

We could improve this technique by changing our code book frequently 
before the patterns are revealed in the ciphertext (the longer the text the more 
patterns will emerge). The ideal frequency for changing the code book is to 
never use the same entry in the code book more than once. For example: first 
translate e to q, but the second time an e is encountered, translate it to b and 
so on, never using the same code book entries twice. Figure 8-3 shows how 
such a nonrepeating code book would be used to encrypt the message “secret 
message.’ 


‘Secret PQCOBS 
Message MIFVTYX 
C—-C 
E— Qplilx 
Gy 
M—M 
R-O 
S— PIFIV 
Code Book 
Plaintext Ciphertext 


Fig. 8-3. Nonrepeating code book example. 


Key Tape Systems 


There is another way to use a code book type system. Instead of having a diction- 
ary (in which some entries will be used many times while others may not be used 
at all), we could use a code book composed of data to be imposed on the plaintext 
instead of replacing the plaintext. This type of code book is called a key tape. 
Imposing one type of data on another can be done in many ways. A simple and 
common way to impose the key tape on the plaintext is by the use of the XOR 
(exclusive or) function (bit wise modula 2 addition). 
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The XOR function is defined as follows: 


O XOR 0 = 0 
O XOR 1 = 1 
1 XOR 0 = 1 
1 XOR 1 = 0 


If our key tape is a random collection of ones and zeros, we could represent 
our data in a similar form (by using ASCII for example) and then XOR our data 
with the key tape to generate the ciphertext. To decrypt, we would XOR the 
ciphertext with the same key tape that was used for encryption. Let’s look at an 
example. Assume “MSDOS’ is our plaintext. This is represented in binary (using 
the ASCII codes of the letters) as 


0100 1101 0101 0011 0100 0100 0100 1111 0101 0011 

If our key tape is 

0100 0110 0111 0011 1001 0000 1100 0110 1011 0100 

the ciphertext (plaintext XOR key tape) would be 

0000 1011 0010 G000 1101 0100 1000 1001 1110 0111 

When we XOR the ciphertext with the key tape again, we get 
0100 1101 0101 0011 0100 0100 0100 1111 0101 0011 


which is our original plaintext. 

A system such as this, where the key tape is random and is used only once, is 
called a one-time pad (or tape) system. Such a system is absolutely unbreakable 
without knowledge of the key tape. The big disadvantage of this type of system is 
that the length of the key tape must be at least as long as the message we want to 
encrypt, and if we have a safe way of storing or transmitting the key tape (or code 
book), why not just use that same means for the message instead? Still, code book 
and one-time pad systems do have their uses. In the military, for example, the code 
book (or key tape) could be distributed during peacetime when safe distribution 
methods were available. Encrypted messages would be transmitted at wartime. 


Cipher Systems 


The other procedure for encrypting data is by using a cipher system. In a cipher 
system, there are two elements: an algorithm and keys. The algorithm enables 
the use of a short key to encrypt a long plaintext. 

Before we look at some cipher systems we should look at our “enemy, the 
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one trying to break our system. The following are some assumptions we should 
make about the enemy if we want to develop a strong cipher system: 


> He or she is just as intelligent as we are and is familiar with the art of 
cryptography. 

> At the enemy’s disposal are the tools needed for serious cryptographic 
work, including such things as letters- and words-frequency information 
and a high-speed computer. 


> Our enemy is in no hurry to break our system. Different data have dif- 
ferent secrecy durations, but let us assume the data we are protecting 
should be kept secret for a long time. Of course, if it takes a thousand 
years to break our system we have a good cipher system—since most 
data will not be secret or useful by the time the system is broken. 


> The enemy knows our encryption algorithm. This is a good assumption 
to make (though there is no need to give the algorithm away on purpose) 
since we would not like our whole cryptosystem rendered useless if the 
enemy managed to get one of our encrypting devices (by getting into our 
embassy, for example). Once the enemy has our encrypting device, it can 
be reverse engineered and its algorithm revealed. 


Data Encryption Standard (DES) 


One important cryptosystem is the Data Encryption Standard (DES), a federal 
standard algorithm for data encryption (U.S. Dept. of Commerce 1977). 
Though some may doubt the wisdom of publishing an algorithm for data 
encryption, we did assume that the enemy knows our algorithm, and by having 
a standard, there is a way for people to use a good, tested algorithm instead of 
forcing them to devise their own untested (and usually very weak) method. 
DES was originally developed after years of work by IBM, was later adopted as 
a standard. Before adoption, the algorithm was rigidly tested by the National Secu- 
rity Agency (NSA), and was declared free of any statistical or mathematical weak- 
nesses. This suggests that it is impossible to break the system using statistical 
methods (such as frequency tables) or to work the algorithm backward using math- 
ematical methods. DES is used by federal departments and agencies to protect all 
sensitive computer data (excluding some data classified according to the National 
Security Act of 1947 and the Atomic Energy Act of 1954). DES is also used by many 
nongovernment institutions, including most banks and money transfer systems. 


The DES Algorithm 


DES works on blocks of 8 bytes (64 bits), encrypting (or decrypting) them using a 
56-bit external (user-supplied) key. Due to the algorithm’s complexity and length, 
we will not go into it in full detail. 
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First, 16 internal keys (K,,Kz . . . Kis) are created from the external key us- 
ing a variety of permutations and left shifts (rotation). 

Next, let's consider the block to be encrypted as a collection of bits num- 
bered 12,3 . . . 64 (see Figure 8-4). First the block is subject to an initial permuta- 
tion stage, which rearranges the location of the bits. The output is then divided 
into two parts, left (Lo) and right (Ro), each consisting of 32 bits. The algorithm 
has 16 steps. Each step receives as input the L and R of the previous stage and 
outputs a new L and R. 

At each stage n(n = 1 to 16) the following is performed: 


La = Rana 


The new left part is equal to the previous right part. 


R, = Lin XOR f(Raa, K,) 


The new right part is equal to the previous left part XORed with the output of 
the Function f (whose inputs are the old right part and the nth internal key (K,). 

The output of the 16th step is then treated by an inverse of the initial permu- 
tation and is the final encrypted output. Decryption is done by passing the en- 
crypted data through the same algorithm in reverse. The cipher Function f is 
defined as 


1. The 32-bit R (right part) is expanded to 48 bits and is now called ER (this 
is done by a bit selection table). 


2. ER is XORed with K, (the nth internal key) giving us 48 bits. These are di- 
vided into 8 blocks of 6 bits each, which are called B,,B2 . . . Bs. 


3. There are 8 substitution functions (S boxes) called S,,S2 . . . Ss. Every S 
box gets an 8-bit input and gives a 6-bit output. Thus B, would go into S, 
to yield a 6-bit output, B,would go into S:, etc. All the outputs together 
are the 32-bit output. 


4. The output of the last stage is again permutated giving the final output 
of the Function f. 


Note that all the exact permutations, S boxes, bit-selection tables, shifts, 
substitutions, etc., used in DES are specified in the standard (but are too lengthy 
to be presented here). 

There is no doubt that the DES is a strong cryptosystem. The strength of 
DES is not only theoretical—it has remained unbroken in spite of many years of 
widespread use. However, DES does have potential flaws. First, some patterns in 
the plaintext will be seen in the ciphertext. If we have identical blocks of plain- 
text (for example, blocks of 8 consecutive blanks), they will be encrypted to iden- 
tical ciphertext (when we use the same key). Another weakness of the DES has to 
do with the relatively short key used, only 56 bits. Thus, there are 2°* (about 7.2 
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Input Block 


Initial Permutation 


L,=Ro [Piste OR HR XOR (Ro, K;) 
ae 
on” ae 
wane i 
Pid 
ee" 
ans 
baA=Rny [Fe=tns XOR Fins Kn) | [Fe=tns XOR Fins Kn) | f(Rm.-1, K 


Rig=lis XOR (Ris, Kis) 


Inverse Initial Permutation 
| Output Block 


Fig. 8-4. Block encrypted by DES. 


x 10%) possible keys. It might be possible to devise a special multiprocessor 
computer that will break messages encrypted by DES by the “brutal force” 
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approach, that is, by generating all possible keys. Such a powerful computer, if it 
can be developed at all, is only within the development capacity of the security 
agencies of the superpowers. 

The DES is an example of a conventional cryptosystem. In such systems, 
there is only one key which is used both to encrypt and decrypt the data. If two 
persons want to pass secret data from one to the other, they must both know the 
same key, so a safe way to transfer the key is needed. 

The following example was created with the File Encrypt program. The 
program is a full DES implementation (that also performs a pre-DES key manipu- 
lation to facilitate using the full range of external keys DES can handle). 


plaintext "MS - DOS" in hex: 4D 53 20 2D 20 44 4F 53 
ciphertext (key=""DES") in hex: 3F 8D DD 29 E7 80 31 1B 


Key Selection and Management 


For using DES (as well as other encryption and password systems), we must choose 
secret keys (or passwords). Though this may seem an easy task, it is not. A good key 
is one which cannot be guessed easily, yet one that we can easily remember. Using a 
good ciphersystem such as DES will not help us if we keep a written note of our 
password lying around. On the other hand, forgetting the key used to encrypt data 
with DES will make decryption absolutely impossible. The worst keys are the most 
obvious ones: IBMPC, names of people or places, telephone numbers, birthdates, 
English words (there is only a limited number of words and a computer can try all 
of them very quickly), etc. Reasonably good keys are those that would seem ran- 
dom to anyone but you, yet you have a method to remember them, for example, 
the third letter of every word of a famous saying. As a rule of thumb, longer keys 
and keys that contain different types of symbols (such as letters and numbers) are 
to be preferred. The best keys are those which are randomly generated, but they 
are easily forgotten. This problem can be overcome by keeping all the passwords in 
a file that is encrypted with a master password. 


RSA and Public Key Systems 


In a public key cryptosystem, keys come in “matching” pairs. One key (the public 
key) is used to encrypt and the other key (the private key) is used to decrypt data 
that was encrypted with the matching public key. Obviously, it is critical that the 
private key cannot be derived from knowledge of the public key. The advantage 
of a public key cryptosystem over a conventional one is that there is no need to 
have a safe method to transfer keys between different parties. It is possible to 
publish a telephone book listing the public keys of all the users of the system. If 
party A wants to encrypt a message so that only party B can access it, the public 
key of party B will be used, but only the private (secret) key of party B can be 
used to decrypt such a message, as shown in Figure 8-5. 
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Public 
Key 


Plaintext Ciphertext 


Private Key 


Fig. 8-5. Public key cryptosystem. 


Public key cryptosystems are based on the use of trapdoor one-way func- 
tions. The term “one-way” suggests that it is easy to compute the function in one 
way (encrypt the data if you know the public key), but it is very difficult to com- 
pute it in the other direction (decrypt the data). The term “trapdoor” suggests 
that if you have certain secret knowledge (the private key), it becomes easy to 
compute the function in the other direction (decrypt). The most important pub- 
lic key system today is RSA, named after its inventors: Rivest, Shamir, and Ad- 
leman. We willlook at the RSA algorithm in some detail. Do not be worried if you 
get lost in the calculations; you can get the general idea of the algorithm without 
necessarily following all the calculation’s details. 

Before we can understand the RSA algorithm we need to define a few 
terms: 

Prime Number. p is a prime number if it has only two divisors (1 and p). 
Examples of prime numbers are: 3, 5, 7, 11, 13, etc. 

Relatively Prime. Two numbers: e and d are called relatively prime if they 
have no common divisor except 1. For example: 9 (whose divisors are 1, 3, 9) is 
relatively prime to 10 (divisors 1, 2, 5, 10) while 9 is not relatively prime to 12 since 
3 is acommon divisor of both. 

Modula. If i and j are integers, i modula j is the remainder of dividing i by j 
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using integer division. For example: 31 modula 3 is 1 because 31 + 3 = 10and 1 
remainder; 5 modula 3 = 2(5 + 3 = 1and 2 remainder); 20 modula 5 = 0 (20 
+ 5 = 4 with 0 remainder). 

To use the RSA algorithm, we first generate our private and public keys 
with the following procedure: 


1. Choose two very large prime numbers; call them p and q. 
2. Define n as the product of p and q (n = p x q). 


3. Pick a large random number, to be named d, which is relatively prime to 
(p — 1) x q — 1). 
4. Define an integer e, so that (e x d) modula ((p — 1) x (q - 1)) = 1. 


5. Establish our public key as the set of two numbers n and e, and our pri- 
vate key as the set of numbers n and d. 


Now when we want to encrypt data for a person whose public key is (e, n), we 
would do the following: 

First, represent the plaintext as an integer between 0 and n-1. This is done 
by breaking the plaintext into a series of blocks, and representing each block as 
an integer. Let's call the number representing our plaintext block M. Next, raise 
M to the power e. The modula n of this is the ciphertext for this block, and will be 
named C. 

To decrypt the message, using the corresponding private key (d, n), one 
should raise C to the power d. The modula n of this is the original plaintext. 

Here is a simple example using the procedure just listed: 


1. Choose p = 3 and q = 11 (in practice we would use much larger 
primes—100-digit or more primes are suggested). 


2.n = 33(3 x 11) 


. (p — 1) X q — 1) = 2050 we need a number relatively prime to 20, for 
example: 3,i.e.,d = 3. 


oy) 


4. We need to choose e so that (e x d) modula ((p — 1) x (qq - 1)) = 1.In 
our case (e <x 3) modula 20 = 1.So wecan usee = 7(7 X 3 = 21 and 
21 modula 20 = 1 because 21 + 20 = 1 and 1 remainder). 


a 


. We publish our public key asn = 20 ande = 7. Our private is (3, 20), 
meaning n = 20andd = 3. 


Now, suppose someone wants to send us the message 
CAB 


First, the sender represents the message as blocks of numbers with values 
0 to 32. Let's assume the representation is A = 1,B = 2, etc., so the numeric 
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representation of the message is 3 1 2. Next, the sender looks up our public key 
which is (7, 33) (e, n). Now comes the process of encrypting the message by rais- 
ing the value of every block to the power 7 modula 33 as shown in Table 8-2. The 
numeric representation of the encrypted message is: 9 1 29. 


Table 8-2. Encryption Conversion Chart 


M block To the power of 7 (e) Modula 33 (n) 
3 2187 9 

1 1 1 

2 128 29 


When we receive this message we decrypt it by raising every block to the 
power 3 (d) modula 33 (n) as shown in Table 8-3. The decrypted message is: 3 1 2, 
the original message. 


Table 8-3. Decryption Conversion Chart 


Encrypted block To the power of 3 (d) Modula 33 (n) 
9 729 3 
1 1 1 
29 24389 2 


The strength of RSA is based on the assumption that it is very hard to de- 
rive the private key from the public key. This is based on the fact that the private 
key can be derived by factoring (finding the divisors of) n. Since n is a very large 
number (a number with at least 200 digits is recommended) and there are no 
known effective algorithms to factor such large numbers, it would take very long 
to do this (requiring over 1073 operations). Unfortunately, the fact that until now 
no efficient algorithm was found to factor very large numbers does not prove 
that no such algorithm exists, and if such an algorithm is found, this system will 
become worthless. Also, there might be a yet unknown algorithm to derive at 
the secret key d without having to factor n. 


Data Encryption and MS-DOS 


In password protection systems, we found that implementing them at lower ac- 
cess levels (BIOS instead of DOS) improves the system by making bypassing more 
difficult. On the other hand, in a system based on data encryption, it is better to 
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implement the system at higher access levels, consequently achieving greater 
control over who has what access to which data. Here, we are not worried about 
the system being bypassed—anyone is welcome to look at our encrypted data. 
An encryption system that works at the BIOS level (intercepts software In- 
terrupt 13h) must treat the hard disk it protects as one whole unit, either grant- 
ing or denying access to it all. On the other hand, if our encryption system 
intercepts data access requests at the DOS level, it is possible to give various peo- 
ple different access privileges by encrypting different files with different keys. 
The ideal place for the encryption software is within the application that uses 
the data. This enables access control down to a record or even a field level. For 
example, only the company’s directors have access to the president's salary 
whereas all the secretaries may read the president's home phone number. 


Loopholes in MS-DOS Data Security 


MS-DOS, unfortunately, was not built with data security in mind, so there are 
many loopholes which make sensitive data more vulnerable, even when an en- 
cryption system is in use. 


Deleting a File 


When you delete a file using the MS-DOS DELETE command, or if a program 
deletes a file using the delete file function of DOS, the file is not really deleted, it 
is only marked as such. The file’s data is actually left untouched on the media. 
For DOS, deleting a file means: marking the FAT entries of the file’s clusters as 
“unallocated clusters,’ and marking the file’s directory entry as “unused” 

Since the data that was once your file is still on the media, it may still be 
accessed (for example, through BIOS using absolute sector addresses) and in 
some cases, the entire file can be reconstructed. The data is never really deleted, 
but we hope when the cluster that has your old file’s data is allocated to a new 
file, the new file’s data will overwrite it. Why use the word “hope”? 

As you recall, the clusters on your hard disk are made up of multiple sec- 
tors. When your old file's cluster is allocated to a new file, which only needs the 
space of some of the sectors, only the data in those sectors will be overwritten by 
new data. This implies that many of your current files have data of old deleted 
files appended to them at the end (DOS knows how much data belongs to the 
current file according to the file length field in the directory). 

The solution to this loophole is to physically overwrite the data in your files 
(with zeros for instance) before requesting DOS to DELETE the file (many utility 
programs can do this, including the Scratch option of File Encrypt). 
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Formatting a Hard Disk 


When MS-DOS formats a hard disk (unlike a diskette), it does not really do a 
hardware format (the process of creating sectors in the tracks). Although the 
FAT now indicates that all the clusters are unallocated and the root directory 
now shows that there are no files, actually, all the data that was on the disk be- 
fore the format is still there. 

My solution: do not rely on the DOS FORMAT command to delete the disk’s 
data. Instead, overwrite the data or use a hardware-formatting program. 


Data “Leftovers” 


DOS accumulates the data before writing it to the disk in RAM buffers. The 
smallest amount of data that can be written to a disk is one whole sector (512 
bytes). Thus, at a file’s end, though DOS may have less data to write, 512 bytes will 
always be written. The data in this unused part of the buffer is unpredictable. In 
reality, this will be whichever data just happened to be in the space used as the 
buffer. This can easily be your secret data that just happened to be in the wrong 
place at the wrong time. 

The obvious conclusion is: do not leave any data “leftovers” in the com- 
puter’s RAM. When you are finished using a program that accesses sensitive 
data, turn off the computer and so clear all the RAM. Turning off the power will 
not only prevent someone who uses the computer after you from looking at the 
leftover data in RAM, but will also prevent DOS from using your sensitive data as 
padding for clusters. Of course, programs which are data security-conscious 
will nullify all the decrypted data left in RAM upon their termination. Regretta- 
bly, there are very few such programs. 


Summary 
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In this paper, we reviewed some of the means available to protect your data in 
the MS-DOS environment. The unavoidable conclusion we have reached is that 
any efficient data security system must be based on encrypting the data. The 
algorithm used in an encryption system should preferably be DES or a variation 
based on DES, but so-called proprietary algorithms should usually be avoided 
since they are almost always very simple to break. 

We can only hope that the increase in computer security problems will mo- 
tivate more software developers to incorporate strong security measures into 
their programs. Until then, we can protect our data by the use of stand-alone 
encryption software. 
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The File Encrypt software, a full DES encryption program for the IBM 
PC written in assembly language for maximum speed, is available for 
$69.95 (check or money order, California residents add sales tax) from: Wis- 


dom Software, Inc.; P O. Box 146310; San Francisco, CA 94114-6310 (Phone 
415/566-0754. The program runs under both MS-DOS and OS/2 protected 
mode. For source code availability and integration with other software, 
contact the author at the above address. 
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Michael Geary 


Microsoft Windows is an operating environment and software library de- 
signed to let you write MS-DOS applications with a modeless, graphical user in- 
terface. This user interface bears a striking resemblance to the Macintosh and, 
likewise, Windows programming and Macintosh programming share many im- 
portant concepts. In particular, the modeless user interface requires an applica- 
tion program structure that’s quite different from traditional DOS applications. 


Who's in Charge Here? 


What do we mean by a modeless user interface? Many application programs 
have their user interfaces built around a variety of different modes. A mode is 
simply a particular state in a program that changes the meaning of the user's 
input or limits the choices the user has available. For example, some word 
processors have a menu mode, edit mode, insert mode, delete mode, and per- 
haps a few others. The menu mode may well have several levels of submodes 
within itself: you make one menu choice, it leads to another, and another, until 
you finally select the operation you wanted in the first place. Modes are often 
used in a well-intentioned attempt to simplify things for the user, but they usu- 
ally backfire. The novice user is puzzled—and the experienced user irritated— 
when choices are restricted this way. It’s the old problem of, “I'm here in the 
menu tree, now how do I get over there?!” 

Unfortunately, modes happen to be convenient for the application pro- 
grammer. As soon as you write a little piece of code like this: 


printf( "Enter account number:" ); 
scanf( "%10s", acctnum ); 
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you have put the user into enter-account-number mode. If the user has forgotten 
the account number, it’s time to escape out of this section of the program, work 
through a couple of menus to get to the account number list, exit back out 
through those menus again, and come back through more menus back to enter- 
account-number mode. Yet, this kind of code is so easy to write that many appli- 
cations are programmed this way: prompt the user and input a choice, prompt 
again and input another choice. At each step, the user is limited to just those 
options that the program allows at that point. 

One of the main goals of MS Windows is to avoid this kind of user interface, 
replacing it with one in which the user, not the programmer, is in charge. To 
accomplish this takes a radical restructuring of applications. (See Essay 1, A 
Guided Tour inside MS-DOS, by Harry Henderson, for a general discussion of 
approaches to the MS-DOS user interface.) 

There are many different kinds of windows you can use, and just choosing 
how to set up the different windows can be a real challenge. The program we 
present called SPY can tell you what kinds of windows any application uses, and 
is also a handy tool for debugging your own applications to see if your windows 
are set up the way you intended. 


Windows and Messages 
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The way Windows avoids modes and puts the user in control is by doing just the 
opposite of a traditional DOS application. Instead of letting the program's flow of 
control be the governing factor, a Windows application spends most of its time 
waiting for messages. In general, each message is directed toward a specific win- 
dow. Each window in an application has a window function, whose job is to pro- 
cess messages for that window. 

For example, if the user clicks the left mouse button in a window, Windows 
generates a WM_LBUTTONDOWN message to notify the window function that the but- 
ton is down, and then a WM_LBUTTONUP message when the button is released. 
These messages are delivered to the window function through calls to that func- 
tion. Note that the application doesn’t “ask” for mouse input—it's the user’s action 
of pressing the button that causes this input. A window function never knows 
what message it is going to receive next. When it receives any particular mes- 
sage, its job is to process that message and then return as soon as possible. In 
fact, one good way to think of a window function is as a little machine whose job 
is to respond to messages generated by the user or by Windows. The fact that 
window functions process messages generated by the user's actions, instead of 
asking the user for input, allows the existence of the modeless user interface. 

MS Windows generates messages for mouse and keyboard input and also 
for every other situation where an application needs to be notified of some 
event. For example, there are messages to let a window know when its size or 
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position has changed, when it needs to have its contents redisplayed, or when a 
menu selection is made. Messages are one of the most important keys to under- 
standing Windows applications. 


Getting the Message: WinMain and Friends 


How does a message actually get to a window function? First, each application 
has a message queue, a first-in, first-out (FIFO) queue to hold messages waiting to 
be processed. A message queue is needed simply to allow type-ahead and 
“mouse-ahead”’ (The standard IBM BIOS type-ahead buffer would be inadequate 
for Windows applications—Windows provides much more extensive keyboard 
information to the application.) 

The main program of any Windows application looks something like this 
(the example is simplified and will not run in this form): 


int WinMain() 


{ 
MSG msg; 
/* Any initialization would go here */ 
/* Main message loop: */ 
while( GetMessage( &msg ) ) f 
DispatchMessage( &msg ); 
} 
return 0; 
} 


As you can see, there's not much to it—after doing any needed initialization 
(such as creating the application's windows), the program settles into a loop call- 
ing GetMessage and DispatchMessage. GetMessage retrieves the next message 
from the application’s message queue and fills in the msg structure with informa- 
tion describing the message. This structure includes 


[> the window handle for the window that is to receive this message (When 
you create a window, Windows assigns a window handle to it and returns 
that handle to you. Every time you refer to a window, you use its window 
handle, and each message for a window includes the window handle.) 


= the message number, a numeric code identifying the message (These 
codes are represented by #define constants in C, such as the 
WM_LBUTTONDOWN and WM_LBUTTONUP messages we mentioned above.) 


243 


Section 2: Programming Tools and Techniques 


244 


“+ two additional parameters, called wParam and lParam (These are a 16-bit 
value and a 32-bit value, respectively, and contain information that varies 
depending on the particular message number.) 


- the mouse position and the time in milliseconds since Windows was started 
(These two structure fields are usually ignored, since the same information 
is repeated in wParamor lParam for those messages that deal with mouse 
position or time of day.) 


Strangely, WinMain doesn’t do anything with all this information once it's re- 
ceived it except immediately call DispatchMessage, passing it the msg structure. 
This is where the real work begins, because DispatchMessage calls the window 
function, passing it the information from the msg structure. 

Actually, Windows could have done all this internally. The reason for having 
this message loop in the application itself instead of down inside Windows is just 
to give a little more flexibility—there are always those situations where you want 
to get sneaky and do something a little out of the ordinary with messages. This 
message loop gives you one more place to do that, by putting extra logic between 
the GetMessage and DispatchMessage calls. MS Windows provides several func- 
tions such as IsDialogMessage that are used this way. 


Window Functions 


When DispatchMessage receives a message, it calls the window function for the 
appropriate window. A window function looks something like this: 


LONG FAR PASCAL ThisWindowFunction( hWnd, wMsg, wParam, lParam ) 


HWND hWnd; /* Window handle */ 
WORD wMsg; /* Message number (WM_something) */ 
WORD wParam; /*x 16-bit parameter */ 
LONG (Param; /* 32-bit parameter */ 
{ 
switch( wMsg ) 
{ 
case WM_XXXXXXXX3 
/* process one kind of message */ 
return OL; 
case WM_yyyyyyyy: 
/* process another kind of message */ 
return OL; 
} 
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/* default processing for all other messages: */ 
return DefWindowProc( hWnd, wMsg, wParam, lParam ); 


The parameters to the window function correspond to the fields we de- 
scribed for the message structure in WinMain; they just happen to be individual 
parameters instead of structure fields at this point. Note that the window func- 
tion is quite simple: it's just a big switch statement, listing each of the messages 
that the application wishes to process for this window. After processing any 
given message, the function returns. (The return value isn’t always 0; for some 
messages, the return value is significant.) 

All messages that aren’t handled explicitly are passed along to a special 
Windows function called DefWindowProc. This function provides the default pro- 
cessing for all messages. Many messages are simply ignored by DefWindowProc— 
keyboard and mouse messages, for example. If you don’t process mouse input, 
it's ignored. There are some messages that must be processed, however, and 
De fWindowProc takes care of these for you. An example would be the WM_NCPAINT 
message, which causes the border, title bar, and scroll bars for a window to be 
displayed. 

DefWindowProc also has defaults for some messages that you might want to 
handle specially. For example, the WM_CLOSE message is a request to destroy 
(close) a window. DefWindowProc calls the Dest royWindowfunction, so the window 
is immediately destroyed. Many applications’ window functions process this 
message themselves, so they can put up a “Do you want to save . . .” message 
and call DestroyWindow only if the user confirms. 

In fact, that is why there is a default window function like this. It would have 
been possible for Windows to just automatically take the “standard” actions for 
various messages and never send them to your window function in the first place. 
Many of the messages passed to DefWindowProc are ones you're not likely to be 
interested in, but passing them through your window function gives you the 
chance to intercept any and do something special with them when necessary. 


Events of the Day 


Messages provide a natural way to handle keyboard and mouse (or other point- 
ing device) input without locking the user into different input modes. Windows 
generates messages for every keystroke, mouse click, and mouse movement, and 
addresses each message to a particular window. 


_Mouse Messages 


Mouse messages are generally sent to the window underneath the mouse cursor. 
When the user rolls the mouse around, Windows sends WM_MOUSEMOVE messages 
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to each window the cursor moves across. These messages include the mouse 
cursor position, relative to the window's client area, along with a set of bits tell- 
ing which mouse buttons are down and whether the Ctrl or Shift keys are down. 
There's also a message sent each time the user presses, releases, or double-clicks 
a mouse button. Although many Windows applications use only a single mouse 
button, Windows supports up to three buttons, and each button can generate 
those three kinds of messages. The WM_LBUTTONDOWN and WM_LBUTTONUP messages 
fall into this category. 

There is an important exception to the rule that mouse messages go wherever 
the mouse is pointed. Any window can take over mouse input with the SetCapture 
function. This function causes all subsequent mouse messages to be directed to a 
specific window. No other window will get mouse messages until ReleaseCaptureis 
called. These functions are commonly used for “dragging” operations. The applica- 
tion calls Set Capture when the user presses the mouse button and ReleaseCapture 
when the button is released. In between, the capture window specified in the Set- 
Capture call gets all the WM_MOUSEMOVE messages. The autoscrolling during this lets 
the window control the dragging without “losing” the mouse if the user happens to 
roll it past the edge of the window. Text selection in Notepad or Write is an example 
of this use of SetCapture and ReleaseCapture. 


Keyboard Messages 


If you have ever struggled with the restricted keyboard interface of DOS and 
BIOS, you will really appreciate the flexibility of Windows’ keyboard handling. 
Unlike BIOS, which throws away perfectly valid keystrokes like the infamous “5” 
key on the numeric pad, Windows sends keyboard messages on every keyboard 
event. Your window function gets a WM_KEYDOWN message each time a key is 
pressed, and a WM_KEYUP message each time a key is released—for every key, even 
the shift keys. Windows defines a list of virtual key codes, and passes you that 
code as well as the actual keyboard scan code. Autorepeat keys also generate 
WM_KEYDOWN messages, but there's a flag passed with the message telling you 
whether it’s an actual keypress or an autorepeat. This gives you complete con- 
trol over the keyboard handling. 

Windows pushbuttons are a good example of the kind of flexibility these 
keyboard messages can give. When you press the space bar on a pushbutton, 
the button is highlighted, remains highlighted while you hold the space bar 
down, and goes back to its normal state when you release the space bar. It also 
sends the parent window function a notification message (I've been clicked) 
when you release the space bar. Under DOS, you couldn’t have this kind of user 
interface without writing your own keyboard interrupt handler, because BIOS 
doesn’t tell you when the key is released. With Windows, it’s easy: Highlight the 
button on the first WM_KEYDOWN, ignore the autorepeat WM_KEYDOWN messages (by 
checking the autorepeat flag), and on the WM_KEYuP, remove the highlight and 
send the notification message. 
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Besides this raw keyboard handling, there is an ASCII keyboard message 
available as well. This message, WM_CHAR, is more like the traditional keyboard 
input. You get a WM_CHAR message for every actual ASCII character input. For ex- 
ample, if you press Shift-A, you get four raw messages: WM_KEYDOWN of the Shift 
key, WM_KEYDOWN of the A key (but it doesn’t tell you whether it’s an upper- or 
lowercase A!), WM_KEYUP of the A key, and wM_KEYUP of the Shift key. You just get a 
single WM_CHAR message, with the ASCII code for capital A. You can use the key- 
board at whichever level suits your application, or mix and match as needed. It's 
common to check the WM_KEYDOWN and WM_KEYUP messages for cursor keys and 
similar functions, and the WM_CHAR messages for actual text input. 


Input Focus 


One question remains: How does Windows know where to send keyboard input? 
At any time, one window owns the input focus, and keyboard input is always 
sent to this window. This is different from the mouse, which sends messages to 
different windows as you roll across them. Keyboard input goes to the window 
with the input focus, regardless of where the mouse is located. The user can set 
the input focus to a window by clicking the mouse in it, by using the Alt-Tab/Alt- 
Esc keys to switch among the windows, or by calling the SetFocus function to 
change the input focus to a different window. 

When the Windows user changes from one window to another with a 
mouse click or the Alt keys, that actually doesn’t directly set the input focus to that 
window. First, the window becomes the active window and receives a WM_ACTIVATE 
message. The active window and input focus are closely related, but not the same. 
The default processing for WM_ACTIVATE does set the input focus to that same win- 
dow with a SetFocus call, but it doesn’t have to be the same. For example, in a 
dialog box, the active window is the dialog box window itself, but the input focus 
is directed to one of the items inside the dialog box. This is done by processing the 
wM_ACTIVATE message. Also, if a window is iconic, it generally doesn’t take any key- 
board input other than the Alt keys, so the default code for WM_ACTIVATE doesn’t 
set the input focus there if the window is iconic. By the way, Windows sends 
WM_SETFOCUS and WM_KILLFOCUS messages to your window function to let it know 
when it is getting and losing the input focus. (If all these messages were telegrams, 
your Windows application could make Western Union rich!) 


Window Rectangles 


The screen area for a window is defined by two rectangles: the window and the 
client. The former gives the window position on the size on the screen and cor- 
responds to the actual border of the window. The client rectangle defines an 
area within the window rectangle that the application's window function (the 
“client”) will use. The region in between—the title bar, menu bar, scroll bars, fat 
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borders, etc.—is called the “non-client area.” Normally, a default window func- 
tion inside Windows manages this area, but an application program can take 
over if it needs to. The client area is really a coding convenience, giving the win- 
dow function a nice, well-defined area it can work in. 


Window Styles: Overlapped, Popup, Child 
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There are three major categories of windows: overlapped, popup, and child. 
The main difference between them is the screen space they reside in. Over- 
lapped and popup windows share the full screen as their display space, and are 
defined in terms of absolute screen coordinates. They are clipped at the edge of 
the screen, and also clipped relative to each other wherever they overlap. This 
means they won’t interfere with each other's display space. If a portion of one 
window is hidden by another window sitting on top of it, any attempt to display 
something in the hidden portion is ignored. 

What’ the difference between an overlapped and a popup window, if they 
can all overlap each other? Well, “overlapped” is a bit of a misnomer, since popup 
windows can also overlap. The fact that we even have these two different styles is 
a holdover from MS Windows 1.X. The overlapped windows used to be tiled win- 
dows, which were different from popups. The difference is this: overlapped win- 
dows are all independent of each other and can be made iconic. Popup windows 
cannot be made iconic, and they often have a parent window, which may be 
either an overlapped window or another popup. If a popup window has a par- 
ent, then making the parent iconic will make the popup window disappear until 
the parent is made visible again. Also, the popup window will always be “on top” 
of its parent—if the user tries to bring the parent window to the top, the popup 
will still be on top of it. In most Windows applications, the main application win- 
dow is an overlapped window and any dialog boxes are popup windows. 


Child Windows 


A child window always has a parent, and is always displayed within its parent's 
client area. Child windows can overlap each other, but they are always clipped at 
the edge of the parent's client area. A child window will never show up outside 
the boundaries of its parent, and if you move a window, all its child windows 
come along with it. Child windows are defined in their parent's client coordi- 
nates, that is, a child window with an origin of (0,0) would be at the top left cor- 
ner of its parent's client area. 

Child windows are used extensively in Windows applications, as Figure 9-1 
shows. The control panel has a main window containing one child window. In- 
side that child window are several other child windows, the individual compo- 
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nents of the control panel. Child windows provide a handy way to provide 
different kinds of behavior in different areas of a single application window 
since each child window has its own window function. For example, the MS-DOS 
Executive has three separate child windows: one for the little disk pictures, one 
for the current directory path, and one for all the filenames. This way, each child 
window function can handle its own operations without worrying about the 
others—you just create the windows and let them run. Child windows are also 
handy when you want to take advantage of code that’s already been written. All 
the items in a dialog box are child windows and use window functions that have 
been provided as part of Windows. You don’t have to write your own code to put 
a little edit field inside a dialog box, for example. 


= Fee Control Pane liieae E 


: Stallation Setup Preferences 


Tine Date 
| 2342222 PM | | szrearer | 


Cursor Blink Double Click 
Slow 


Spy on Windows? 


Window 1AF% <Spy?} (51,212;636,474) “Spy on Windows?" 
Window 1630 <CtlPanel} (7,6;327,241) “Control Panel" 
Child window 17E8 (#32770) (8,875328,242) """ 

Child window 184C <{Button} (32,62;152,111) “Time” 
Child window 189C <ScrollBar} (137,76;152,111) °°" 
Child window 18EC {Button} (196,623292,111) "Date" 
Child window 193C <{ScrollBar} (277,70;292,111) ‘** 
Child window 198C {Button} (24,122;168,229) “Cursor Blink” 
Child window 19E4% <{ScrollBar} (32,167;152,182) "" 
Child window 1A38 {Static} (32,145;64,161) "Slow" 
Child window 41DE8 {Static} (128,145;152,161) "Fast" 
Child window 1E2C {Button} (176,122:312,220) “Double Click" 
Child window 1€78 ({ScrollBar)} (184,167;304%,182) °" 
Child window 1ECO <Static}> (184,1455;216,161) “Slow™ 
Child window 1F18 {Static} (272,145;304,161) “Fast™ 


Fig. 9-1. Windows within windows. 


The child windows in the MS-DOS Executive window are not readily appar- 
ent to the user. In fact, it takes a program like SPY to reveal them. They are just a 
coding convenience for the MSDOS.EXE program. The exact same application 
could have been written with a single window and explicit code to handle things 
like mouse hit-testing (determining which area the mouse was clicked in). Using 
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child windows, however, helps you modularize your code, and also lets Windows 
do more of the work for you. 

You can also create child windows that the user can directly manipulate. 
Child windows can have caption bars, sizing borders, and the like, letting the 
user move and size them. In fact, they can look just like overlapped or popup 
windows, and can operate much the same except for being located in their par- 
ent'’s client area. 

One of the few limitations on a child window is that it can’t have any menu 
of its own. It can have a system menu, but no menu bar of its own. (In Windows 
1.X, a child window couldn't even have a system menu, only a close box. That's 
probably one of the most rarely seen features in Windows 1.X applications.) 


Multiple Document Interface 


The Multiple Document Interface (MDI) in Windows 2.0 makes extensive use of 
child windows. Each application has its own top-level overlapped window (and 
any popups as needed), and all the application’s documents or views of docu- 
ments are opened as child windows within this parent. For example, in a MIDI 
(Musical Instrument Digital Interface—no relation to MDI!) sequencer program, 
you might open up child windows for sequence editing, voice editing, MIDI pa- 
rameters, and a control panel. 

The child windows can be moved and sized, and even zoomed (maximized) 
to fill up the parent’s display space. As you select different child windows, the 
parent's menu changes since the child windows can’t have their own menus. This 
is similar to the way some Macintosh programs operate, wherein the title bar 
changes as you select different windows. In fact, running a set of Macintosh ap- 
plications under MultiFinder is much like running Windows. The main visual 
difference is that all menus appear on the top of the screen on the Mac, where 
each main application window has its own menu under Windows. 

The purpose of MDI is to help the user organize and control the different 
applications’ windows. For example, if you want to get that music program out 
of the way for a while, you can minimize (‘collapse” into a single graphic symbol) 
its main window, and all its child windows disappear along with it. 


Window Classes 
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Often, you want to have several different windows that operate the same or a 
similar way. Suppose you have a dialog box with several edit fields. Each one is a 
window. (In fact, every item in a dialog box is a child window.) Although you 
need to be able to refer to each one individually, and each one has unique data 
including its text, the actual program code for each is the same. That suggests 
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they ought to have a common window function and perhaps some common 
data, along with a block of data unique to each window. 

That's exactly what a window class is, defining a collection of windows that 
share a common window function and have some other attributes in common as 
well. Windows comes with a number of predefined window classes. Most of 
these are the various controls or child windows used inside dialog boxes, such as 
the text editing and pushbutton controls. Applications can also create their own 
window classes. In fact, nearly every Windows application creates at least one 
new class for its main window. 

You create a window class with the RegisterClass function, and thus spec- 
ify the information that will be common to the windows of this class. Register- 
Classcopies this information into Windows’ own list of window classes, so that it 
becomes available for creating windows. This information includes 


> the window class name (This is a text string that uniquely names the 
class. The predefined window classes that come with Windows include 
Edit (text editing window), Static (background text), Button (push button, 
radio button, check box), ScrollBar (horizontal or vertical scroll bar), and 
List (list box).) 


» the window function address (This function gets called by Windows 
whenever there is a message for any window in this class.) 


od 


V 


the icon and cursor to be used for windows in this class 


V 


the default menu and background color (or brush) for these windows 


¥ 


the class style, several option bits affecting window operation 


¥ 


two values indicating how much extra space to allocate in the class data 
structure and in each window data structure (Windows provides func- 
tions to read and write this extra data space, giving a convenient place to 
store additional information for your window functions to use—either 
data for the class as a whole or data that's unique for each window.) 


Creating a Window 


Once you've registered a window class, you can create as many windows of that 
class as you like, using the CreateWindow function. The parameters to 
CreateWindow include the information that’s unique (or can be unique) to each 
instance of the window: 


> the window title 

> the parent window, if this is a child or popup window 

= the window's position and size (For a child window, this is relative to the 
parent window’s client area. Otherwise, it's the actual screen position.) 
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~° the window's menu (optional, to override class menu) 


window style, a set of bit flags like the class style, but unique to this win- 
dow (These style flags include things like whether the window has scroll 
bars, a title bar, or a sizing border.) 


One remaining parameter to CreateWindow is the window class name. The 
information that was provided with the RegisterC lass call applies to this window, 
as well as to the other windows of this class. That includes the window function. 
In the example we mentioned above, where you have several text edit fields in a 
dialog box, these are individual instances of the Edit class. Each one has a unique 
position on the screen and contains different text, but they all share a common 
window function, containing the code to do the actual text editing. 


Where Do Messages Originate? 


After you create a window with the CreateWindow function, the window func- 
tion starts receiving all the messages we've been talking about. There are actu- 
ally two very different ways a message can be originated: SendMessage and 
PostMessage. Most of the messages we discussed earlier, including keyboard and 
mouse input, are created with PostMessage calls (or some equivalent functions 
used internally by Windows). PostMessage places a message on an application's 
message queue, where it will be picked up later by a GetMessage/Dis- 
patchMessage loop, such as the one in WinMain. 

There are some messages that CreateWindow sends directly to the window 
function during the window creation process, long before Creat eWindow ever re- 
turns. These messages are created with a SendMessage call. SendMessage is essen- 
tially a direct subroutine call to a window function, bypassing the message 
queue. If you send messages of your own to a window function, the choice of 
whether to use SendMessage or PostMessage depends on whether you want the 
message to be processed immediately or queued up to be processed in sequence 
with other messages. Some messages return data to the caller—these are always 
sent with SendMessage. For example, you can send an EM_GETSEL message to an 
edit control window, and the return value from SendMessage will give you the 
beginning and end of the current selection in the edit control. PostMessage 
wouldn't work for this. 


Graphics Programming in Windows 


In Windows, you are doing graphics programming even if your program is text 
based. Really, that’s always true—text is just one kind of graphics—but in Win- 
dows, there's no avoiding the fact. You’ve got to deal with some unfamiliar con- 
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cepts just to print Hello, world!. We're not going to cover all the complexities of 
graphics here, but will touch on the major concepts needed to make text and 
simple graphics programs work. 


Coordinate Systems and Points 


Every time you do any graphics output (in any environment), it takes place in a 
particular coordinate system that represents either a virtual or physical display 
surface. For a DOS text-mode application, the coordinate system is the 80 x 25 
screen, where you have X coordinates of 0 through 79 and Y coordinates of 0 
through 24. A coordinate system is simply some method for relating X and Y 
coordinates to an actual display, and a point is an (X,Y) coordinate pair. 

In Windows, each window has two coordinate systems: device (physical) 
and logical. Device coordinates refer to actual device pixels, but are normally 
offset so that (0,0) is the top left corner of the window's client area. Logical coor- 
dinates can be assigned in several different ways, either equal to device coordi- 
nates or transformed through some formula to scale the coordinate size. This 
lets you do tricks like the CLOCK and REVERSI programs, i.e., automatically size 
your image to fit the window size without having to do all the scaling computa- 
tions yourself. The mapping mode you use determines how logical coordinates 
are interpreted. 

For a simple text program like SPY, the easiest thing to do is disregard the 
fancier mapping modes and use the default one, called MM_TEXT. In this mode, 
you are always dealing in terms of actual device pixels, so the one complexity is 
that you have to find out how large the characters actually are. Since the font 
size varies with different displays and fonts, Windows provides a function, Get- 
TextMetrics, to let you get this information. 


Rectangles and Regions 


A rectangle is simple. It’s defined by a pair of points, the top left and bottom right 
corners. Although the top left corner is part of the rectangle itself, the bottom 
right corner is just outside the rectangle by one pixel. In other words, if you had 
a2 x 2rectangle (four pixels total) and its top left corner was (10,10), the bottom 
right corner would be (12,12), not (11,11). 

This is actually rather convenient once you get used to it. For example, you 
can calculate width = right — left instead of width = right — left + 1.It also 
lets you represent the empty rectangle (enclosing no pixels at all) as (0,0,0,0). In 
fact, that’s a good way to help keep rectangles straight. Think of them as enclos- 
ing a group of pixels instead of describing the edgemost pixels. 

A region is an arbitrary area of the display space. It can have any shape and 
size, can have “holes” in it, and can be composed of several discontinuous areas. In 
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other words, a region can be any set of pixels. Internally, regions are represented as 
a linked list of rectangles, but Windows doesn't let you get at the internal structure. 
There are a raft of functions to let you create a region, add a rectangle to a region 
(or remove one), create the intersection or union of two regions, etc. 

Regions are powerful tools for graphics programming, and Windows 
makes extensive use of them. One of the most critical is the clipping region that 
is in effect whenever you display anything. This is how Windows lets you display 
inside a window that may have other overlapping windows on top of it. The clip- 
ping region includes only the visible portions of your window, and each pixel 
you try to display is compared with the clipping region and discarded if there's 
another window on top of it. 


Window Painting 


For the newcomer to Windows programming, there are many things that must 
seem pretty strange, and window painting is probably one of the strangest. Even 
if you're sure you've grasped this idea of message-driven programming, you're 
likely to try to paint (display) information in your window the wrong way. You 
discover how to use the TextOut function and successfuly display some text in 
your window. Things look fine, and then you bring up another window on top 
of yours momentarily. Then you close that other window, and . . . your window 
is blank! Or worse yet, part of the text you displayed is still there and part of it 
has disappeared. What happened? 

Well, remember that Windows sends you messages for everything. One of the 
most critical messages—one that nearly every window function needs to handle—is 
WM_PAINT. This message notifies your window function that all or part of its client 
area needs to be displayed. In our little mystery above, you displayed something in 
the window at some other time, but forgot to handle the WM_PAINT message. When 
the other window covered up your window, the text you had displayed was lost. 
When the other window was closed, Windows dutifully sent you a WM_PAINT mes- 
sage to tell you to redisplay your client area. The rest was up to you. 

Regardless of any other window painting you may do, your window func- 
tion always has to be prepared to handle a WM_PAINT message, and display what- 
ever part of your client area needs to be refreshed. There's actually a two-step 
process that leads to a WM_PAINT message being generated. First, part of the win- 
dow becomes invalidated. This simply means that part of the window's screen 
display may no longer be up to date. This can happen when another window 
covers it up or as a result of resizing the window. You can also request that all or 
part of your window be invalidated by calling the InvalidateRect function. Win- 
dows doesn’t send a WM_PAINT message at that time. It simply accumulates the 
invalid areas into an update region. Remember, a region can contain any arbi- 
trary area of the screen. The update region contains those portions of your win- 
dow which have been invalidated. 
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Later on, when the GetMessage call in WinMain (or elsewhere) has exhausted 
all other pending messages, Windows will go ahead and generate a WM_PAINT mes- 
sage for any windows that have any accumulated update regions. Then your win- 
dow function will finally receive the WM_PAINT message and call the special 
BeginPaint function. This sets up a data structure telling you what portion of the 
window needs to be painted, along with other information needed for painting it. 

This deferred processing may sound awfully roundabout, but in practice, 
you generally get the WM_PAINT message pretty quickly. The purpose of deferring 
it is to let your application handle any higher-priority messages, such as key- 
board or mouse input, first. For example, the Alt-Tab command in Windows im- 
mediately highlights each window frame in sequence, letting the user quickly 
step through the applications, but doesn’t let any WM_PAINT messages through 
until the user releases the Alt key. 


Memory Management 


Windows has a very powerful—and complex—memory management scheme. 
There's a heap manager much like the one provided in the C runtime library, 
except it has the almost magical ability to avoid the problem of memory frag- 
mentation encountered in most dynamic memory management schemes. You 
know the problem—suppose you allocate several blocks of memory and then 
free up most of them. You now have plenty of memory free, but it's broken up 
into small chunks by those blocks that haven't yet been freed. Now if you want to 
allocate one large block, you can't. 

To avoid this problem, Windows uses a relocatable memory management 
system. When you allocate a memory block, using the GLobalAl Loc function, you 
don’t get back a pointer to it! Instead, you get a handle to the memory block. 
Even though the memory has been allocated, you don’t yet know its address. 
This way, Windows is free to move the block—and other memory blocks— 
around as needed to avoid fragmentation. If you try to allocate a memory block 
and there is enough free space but it’s broken up into little chunks by other allo- 
cated blocks, there is no problem. Windows will simply move those blocks out of 
the way to bring the free space together into one large block. 

What good is a memory block if you don’t know its address? Not much! 
When you want to actually use the memory, you call the GlobalLock function, 
which locks the block down in memory. Windows will no longer move it around. 
GlobalLock returns the current physical address of the memory, so you can use 
normal C pointer operations to get at it. When you're finished with the memory, 
you Call GlobalUnlock to let Windows know that it’s okay to start moving it 
around again if it needs to. The idea is to leave the block unlocked as much of the 
time as possible, locking it only when you actually access it. 

This may seem like a lot of extra work compared to more traditional mem- 
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ory allocation schemes, and it is. But it gives you the advantage of avoiding the 
old problem of memory fragmentation. In cases where you need instant access 
to a piece of memory without locking and unlocking it all the time, you can tell 
GlobalAl Loc to make the block fixed instead of movable. Then, you get the actual 
address of the block instead of a handle, and the block will never move. Win- 
dows does take the precaution in this case of allocating the block at the low end 
of memory, where it is less likely to cause fragmentation. 

There are a couple of other twists to the memory management. When you 
allocate a block, you have the option of flagging it as discardable. This means that 
Windows is free to discard this block of memory whenever it runs low on space. 
On a discardable block, you can request that Windows call back a notification 
function, that you provide, right before it discards the block. This lets you imple- 
ment a swapping scheme for memory, even though Windows doesn’t have swap- 
ping built in. 

Windows puts these memory management capabilities to good use in man- 
aging program code. Most application code segments, and most of the code that 
makes up Windows itself, is in relocatable, discardable memory blocks. Win- 
dows can move code segments around in memory, discard and reload them as 
needed, all transparently to the application programs. In effect, this gives you an 
overlay system for your code, without any of the drawbacks of traditional over- 
lay systems. You don’t have to create a tree structure for your overlays, and you 
don’t have to worry about which overlays are in memory at any time. Further- 
more, you don’t pay the penalty of frequent overlay loading when plenty of 
memory is available. All you have to do is break up your code into segments, and 
Windows will take it from there. If there's enough memory available, all your 
code can fit into it. If Windows starts to run low on memory, it will discard code 
segments as needed, keeping track of which segments have been executed re- 
cently and discarding the oldest. 

There are actually two heaps. The functions we just discussed access the 
global heap, which is shared among all applications and occupies all of memory. 
Your application also has a local heap, which you can access with a similar set of 
functions whose names begin with Local instead of Global. This heap is private 
to your application and is located in your own O0GROUP along with your static data 
and stack. As in a normal C application, DGROUP is limited to a total of 64K, and 
can be accessed with near pointers instead of far pointers. 


Resources 
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Nearly every Windows application uses resources, and they’re one of those 
things that sounds unfamiliar at first. But, it’s likely you have used them under 
another name in other programs you've written. Suppose you've built a help 
facility into an application. Unless you coded all the help text in your program, 
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you probably created a help file containing the different help screens along with 
some coded information to let your program find the various screens. You may 
have gone further and included all your error messages in this special file and 
other little pieces of data your program needs to load in. Of course, this means 
there's another file for your users to remember to put in the right place for your 
program to find it. Wouldn't it be nice if you could somehow include all this data 
in your .EXE file and have an easy way to get to it? 

That's exactly what resources are. They're chunks of data incorporated 
into your .€XE file that your program can read in dynamically. Each resource has 
a type and a name, which are ASCII strings (or numbers) that identify the re- 
source. Any kind of data can be made into a resource. Windows provides 
predefined resource types and associated functions for the most common data 
items used by Windows applications. For example, the LoadMenu function loads a 
menu description into memory, LoadString loads a text string, etc. There are 
also the generic FindResource and LoadResource functions for additional re- 
source types that you define. 

Windows includes a Resource Compiler (RC), which reads a text file with 
the .RC extension. This file contains data declarations for the resources you 
want to include in your program. RC compiles these declarations into a binary 
format and merges them into your .EXE file. One nice touch here is that RC in- 
cludes the standard C preprocessor. That lets you use #include, #defineand the 
other preprocessor directives in your .RC file. This is extremely helpful, because 
you can include a .H file in both your C code and your .Rc file, making the same 
symbol definitions available in both. 


The SPY Program 


Now that you've seen how Windows applications work, we can look at our fea- 
tured application, SPY. SPY is a Windows application that does just what its name 
suggests. Specifically, SPY scans through all currently existing windows, regard- 
less of which application created them, gathering up all the information it can 
find about these windows. Then, it displays this information in its own window, 
letting you scroll through it and view it. SPY is both a tool for developing and 
testing applications, and a good example of how a Windows application is put 
together. 


Using SPY 


SPY'’s own window shows a list of all existing windows, whether they happen to 
be currently visible on the screen or not. You can select either a one-line sum- 
mary of each window or a detailed view that displays all the information SPY has 
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Child window 12F0 {Disk} (224,110;5488,132) °" 

Child window 1338 {Path} (224,132;587,147) "“" IS 
Child window 1388 {Dir} (215,151;588,265) ‘* 

Popup window GF18 {wintitle}> (6,465;132,424) °" 

Window 18D8 {MSWRITE_MENU} (2,25446,167) “Urite - ARTICLE.WRI” 
Child window 1DD8 {ScrollBar} (128,14%7;427,162) “" 
Child window 1E1C <ScrollBar)> (426,475441,148) °" 
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Popup window GED4 <{winswitch> (6,0;16,16) °" 

Iconic window 1414 {(FreeMen} (3,4453;39,879) “Freetten™ 


Fig. 9-2. SPY’s summary view. 


picked up—the Show Detail command on SPY’s menu switches between the two 
views. The window list doesn’t change dynamically —it's a “snapshot” of the state 
of the Windows system at the time SPY was started up. You can bring the list up 
to date at any time by selecting New Spy Mission from SPY'’s menu. Figure 9-2 
shows windows owned by the MS-DOS Executive, Write, and SPY itself, along 
with the Tiler and Freemem programs running as icons. Figure 9-3 shows de- 
tailed information about SPY’s own window, which can be scrolled up and down 
to bring the rest of the detailed listing into view. Each line in the summary view 
shows from left to right: 


1. the basic window style: popup, child, iconic, or just plain Window for 
main application windows (Child windows are indented under their par- 
ent.) 


2. the window handle, shown as a 4-digit hex number 


3. the window class name, shown here in curly braces (The braces aren't 
part of the actual name.) 
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Window handle: 1AF& 
Class name: Spy? 
Window title: Spy on Windows? 
Parent window handle: 00898 
Class function, Window function: 216B8:60F4, 2188: 00F4 
Class module handle, Window instance handle: 216B, 628E£ 
Class extra alloc, Window extra alloc: 6, @ 
Class style, Window style: 0603, 14FF S901 
Henu handle: GA86 
Brush, Cursor, Icon handles: 86086, 0886, 029A 
Window rectangle: Left= 74, Top= 171, Right= 627, Bottam= 478 
Client rectangle: Left= 68, Top= 06, Right= 527, Botton= 241 


Yindow handle: 1688 
Class name: Session 


Fig. 9-3. SPY’s detail view. 


4. the window coordinates, shown as actual screen coordinates, in this or- 
der: (left,top;bottom, right) 


5. the window title, in quotes 


The detailed view shows a number of additional items, and each item is labeled. 

One handy use for SPY is to find out just how other applications are setting up 
their windows. Figure 9-4 shows an example, SPY looking at Notepad. SPY's display 
reveals that Notepad’s main window contains one child window, of the Edit class, 
which invokes Windows’ built-in text editor. That's how Notepad works—it simply 
creates a multiline edit control inside its main window, just as you could create one 
inside a dialog box. This is clever. It lets Notepad use the editing code built into 
Windows, so the Notepad program itself just has to take care of creating the child 
window, resizing it when the parent window size changes, and handling the file /O 
operations and goodies like Search. The actual text editing is handled by the win- 
dow function for the Edit class, with no effort on Notepad’s part. 
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Window 1804 {Notepad} (18,8;517,278) “Notepad - READHE.TXT" 
Child window 1908 {Edit} (2%,56;498,256) "" R 
Popup window GF10 {wintitle} (0,465;132,424) °" 
Iconic window 1498 {Tiler?} (3,485;39,842) “Tiler” 
Popup window GED4 {winswitch}> (6,8;10,18) °° 
Iconic window 141% {Freeten} (3,443;39,479) “FreeHen” 
Iconic window 16A8 {Session} (3,369;39,465) “HS-DOS Executive“ 
Child window 12F8 {Disk} (11,371;275,393) °" 
Child window 1338 <Path} (11,3933;3974%,468) "" 
Child window 1388 {Dir} (2,412;375,4%66) °" 


Fig. 9-4. Notepad reveals a child window of the edit class. 


SPY is also handy for debugging your own applications. If you run into a 
situation where your windows aren't operating correctly, you can have SPY take 
a look at the situation. In an application like my own SQLWindows database ap- 
plication development system, which creates and destroys all kinds of windows 
as it executes, I’ve found this very handy. When things haven’t looked quite right, 
SPY has often pointed the way toward the problem. 


How SPY Works 


Even though SPY is rather unusual, its programming is typical of a Windows 
application. Understanding how SPY works will help you understand how any 
Windows application is put together because, like most Windows applications, 
SPY is built around its window functions and messages. Let's start at the begin- 
ning, with SPY’s main program, WinMain. (In reading the listing, you can find 
functions more easily by noting that they’re alphabetized, so don’t look at the 
beginning of the listing for winMain!) 
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WinMain 


We gave a shortened example earlier of a WinMain function, and SPY’s main pro- 
gram follows that model. You'll note that WinMain has several parameters: 


hInst and hPrevinst are the instance handles for this instance and the pre- 
vious instance of SPY. A Windows user can start up multiple copies of an 
application, and Windows assigns an instance handle to each. Several Win- 
dows functions, such as CreateWindow, need your instance handle as a pa- 
rameter. The reason for giving you the previous instance handle is for 
cases where you want to copy data over from one instance to the next. A 
Windows application, just like a DOS application, can have command-line 
parameters. SPY doesn’t happen to use these, so we ignore this parameter. 


--- nCmdShow is the parameter that should be passed to a ShowWindow call when 
we create our main window. Normally, a Windows application starts up 
with its window visible, but the user can request that it be started with an 
iconic window by holding down the Shift key while starting the program. 
The nCmdShow parameter communicates this to the application. 


WinMain itself is quite simple. It calls our Initialize function to get things 
started, then falls into the main message loop. This loop is much like the one we 
looked at before, with one additional function call: Trans lateMessage. This is a 
“busywork’ function that every Windows application has to call in its main loop. 
It translates the raw keyboard messages into their ASCII equivalents, and also 
takes care of some necessary processing for the System (Control) menu. 

The main message loop terminates when GetMessage returns zero. This 
doesn’t mean there aren’t any more messages— GetMessage just goes to sleep for 
a while in that case. The zero return means that a WM_QUIT message has been 
received by GetMessage. In SPY, this happens when PostQuitMessage is called in- 
side SPY's window function, and that call is made when the window is destroyed. 


Windows Naming Conventions 


The naming conventions in the SPY program may be unfamiliar to many C pro- 
grammers. SPY uses the conventions followed in the Windows documentation 
and many Windows applications. Function names, as you've seen, generally fol- 
low a verb-noun model, describing what they do, e.g., CreateWindow or 
GetMessage. 

Most variable names have a lowercase prefix that tells the variable type. 
Some of the prefixes used in SPY are listed in Table 9-1. The np and lp prefixes 
are often followed by additional prefix letters specifying what is pointed to, as in 
lpszCmdLine, which is a far pointer lp to a zero-terminated string sz. 
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Table 9-1. Variables in SPY 


er 


Prefix Variable Type 

h Handle 

n Integer 

b Boolean value 

dw Double-word (unsigned long integer) 
SZ Zero-terminated string 

np Near pointer 

Ip Far (long) pointer 


Although a Windows application can use any kind of naming convention 
internally, these conventions turn out to be very handy. It helps to know the type 
of a variable from looking at its name, and the long, descriptive function and 
variable names make the code much more readable and maintainable. 


Initialize 


SPY’s Initialize function gets everything started. Its main job is to create our 
window. First, we must register the window class with a RegisterClass call. 
Note, however, that this is done only on the first instance of the program. Subse- 
quent instances can use the same window class. You probably wouldn't want to 
run multiple instances of SPY, but it's important to program correctly for multi- 
ple instances, or else to disallow them completely by exiting out of WinMain 
whenever hPrevInst is nonzero. 

One other step that’s done differently, depending on whether this is the 
first instance or not, is loading of text string resources. In the first instance, we 
actually load them from the .€XE file with LoadString calls, then in subsequent 
instances use the Get Instance function to copy them over from the previous in- 
stance. This isn’t really necessary, but it speeds up loading of subsequent in- 
stances if you can copy over some of the data like this. Also, in a “real” Windows 
application, every text message should be placed in the .Rc file and loaded with 
LoadString. This makes it easier to produce foreign-language versions of your 
program by isolating all the strings in one place outside the actual program 
code. Then, you can just edit the .Rc file to change languages. {1 cheated to keep 
the listing size down, and coded most of SPY’s strings right in the source code— 
don’t follow my example on this!) 

After registering the window class, we create SPY’s main window with a 
CreateWindowcall, setting the window position and size explicitly and placing the 
window in approximately the center of the screen. Many programs let Windows 
assign a default position and size by passing the special value Cw_USEDEFAULT for 
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the X and nWidth parameters. This is also where we specify that our window 
will have scroll bars, by giving the WS_HSCROLL and WS_VSCROLL style options. 

After creating the window, we make it visible with a ShowWindow call, and 
post a WM_COMMAND message to the message queue. Later, as we pick up messages 
in our main message loop, this message will get picked up and processed, just as 
if the user had picked the New Spy Mission menu item. This causes the first in- 
formation display in the window. 

Initialize also takes care of a few other details. It determines the charac- 
ter height and width for the system font, necessary information to properly 
paint and scroll the window. It also preallocates a global memory handle for the 
INFO structure, although it doesn’t yet allocate any memory for it (well, it allo- 
cates one byte). This simplifies other parts of the program where this handle is 
used. We don’t have to worry later about whether this handle has been initial- 
ized or not. 


SpyWndProc 


This is where the action is. Once we've created our window, the main program 
settles into its message loop, dispatching messages to SpyWndProc as they come in. 
Like most window functions, this one is a switch statement, with one case for 
each message we wish to process. Messages that we're not directly concerned 
with are passed through to DefWindowProc for the standard Windows processing. 


WM_COMMAND 


We get WM_COMMAND whenever the user selects one of the items from our menu, 
either with the mouse or keyboard. WM_COMMAND is also used for notification mes- 
sages when a window has child windows. (We're not concerned with these 
here.) For this message, wParamcontains the command ID number, as assigned in 
the spy.Rrc file. 

One of the most important menu items is cMD_sPy, the New Spy Mission 
command, which causes the list of windows to be scanned by calling the Spy~ 
OnAl Windows function. Figure 9-5 shows SPY’s menu just before selecting the 
New Spy Mission command. Figure 9-6 shows SPY's menu just after selecting the 
command. The popup window listed at the beginning of SPY’s display is the 
menu from Figure 9-5. Popup menus themselves are windows, and the com- 
mand was executed before the menu window disappeared. Remember, CMD_SPY 
comes in after initialization even if the user doesn’t select it, because we posted it 
to the message queue in the Initialize function. CMD_EXPAND (Show Detail) tog- 
gles the detail/summary view by toggling our internal flag, bExpand, checking or 
unchecking the menu item with a CheckMenuItemcall, and invalidating the entire 
window with an InvalidateWindow call so it will get repainted. 
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MS-DOS Executiv 


ARTICLE .BAK 

ARTICLE .DOC 

ARTICLE .STY . 
BYTEART .DOC SPY164 EXE 
DEB .BAT W.BAT 
OUTLINE .STY¥ SPY. 10 


aSpy on Windows 


Window 1638 <Spyt} (18,220;629,423) “Spy on Windows?” 
Window 16A8 {Session} (19,7;629,207) “MS-DOS Executive” 
Child window 12F@ {Disk} (2h, 65:352,77) "" 
Child window 1338 {Path} (344,58 623,73) ror 
Child window 1386 {Dir} (15,77;624,282) “” 
Popup window GF16 <{wintitle} (38,466;82 a79yp0" 
Iconic window 1498 {Tiler?} (42,424;78,460) “Tiler” 
Iconic window 1414 {Freettem} (3,424;39,466) “Freettem™ 


Fig. 9-5. SPY’s menu before selecting New Spy Mission. (The 
arrows show which window is described by each line 
of SPY’s display.) 


The cCMD_A80UT (About Spy . . . ) gives an example of how to display a modal 
dialog box. Despite all the nasty things said about modes earlier, there are still 
situations where we want to display something or get some user input and sus- 
pend the rest of the application temporarily. We do this with a modal dialog box. 
One caution here, though. Any time you're tempted to put up a modal dialog 
box, think twice about it and see if a modeless dialog could be used. If so, your 
users will appreciate it! It gives them more flexibility in using your application. 
One of the more common design flaws I’ve seen in Windows and Macintosh ap- 
plications has been overuse of modal dialogs. 


WM_DESTROY 


WM_DESTROY comes in when our window gets destroyed by a Dest royWindow func- 
tion call. This can happen either by selecting the Exit command on SPY’s menu 
(see CMD_EXIT under WM_COMMAND), or by selecting Close from the Control menu 
(the same as double-clicking the Control menu icon). In the latter case, the 
DestroyWindow call is generated inside DefWindowProc. Control menu items ‘all 
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1 BSS] o—— © C= cznrtve-c \winpows 
| Dac BROWSER.EXE  CLOCK.EXE COURE .FON DIGICLOK .EXE 
i] Draw CALC .EXE COMM .DRU CRUNBLE.EXE  DISKLOOK.EXE 
| DRIVERS CALENDAR.EXE COHHAND.C CTLCOLOR.EXE DISPINFO.EXE 
CARDFILE.EXE CONTROL.EXE CUTPAINT.EXE DISPLAY .DRU 
CHANGE .C COURA.FON DATABASE.C  DLGBOX.EXE 
CLIP .C COURB.FON —dDEB.BAT DRAG .C 
ST.APP CLIPBRD.EXE COURC.FON — DEBC.BAT DTHODULE .C 
oc.c CLIST.APP COURD.FON © DEBW.BAT DUMP .c 


re Spy on Windows? 


RULER (392768) (8,264;159,368) °" 
|) (2,2195638,442) “Spy on Windows?” 


Show Detail On> (2,2;638,217) “HS-DOS Executive" 
@ {Disk} (16,50;280,72) “" 
a: {Path} (272,53;3632,68) "" 
% ® {Dir} (7,723633,212) * 
About Spy--- {wintitle} (38,461;82,480) ‘" 


Iconic window 1498 <{Tilert} (42,4433;78,879) “Tiler” 
Popup window GED’ {winswitch}> (6,60;10,10) "" 
Iconic window 1414 {FreeMem} (3,443;39,479) "FreeMen™ 


Fig. 9-6. SPY’s menu after selecting New Spy Mission. 


generate WM_SYSCOMMAND messages, and we pass all those through to DefWindow- 
Proc for the standard processing. All we do on WM_DESTROY is call Post QuitMessage 
to terminate the application. 


WM_HSCROLL and WM_VSCROLL 


We get WM_HSCROLL and WM_VSCROLLas a result of any activity in the horizontal or 
vertical scroll bars, respectively. In both cases, our DoScrol \Msg function handles 
the actual scrolling. This function is fairly lengthy because of the various cases it 
must handle: clicking in the up-arrow or down-arrow, the page-up or page-down 
area, or dragging the thumb. But after calculating the new scroll position based 
on this information, the actual scrolling is simple. We call SetScrollPos to set the 
scroll bar itself to the new position—this doesn’t happen automatically. Then we 
call ScrollWindow, a very handy function. It optimizes the scrolling by moving 
the actual window contents if there's any overlap between the old and new posi- 
tions (as there would be in a single-line scroll), then calls InvalidateRect to cause 
the remaining area to be repainted. Like all window painting, this part gets de- 
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ferred until all other activity is done, so we call Updat eWindow to force the repaint- 
ing to happen immediately. This gives a cleaner appearance to the scrolling. 


WM_KEYDOWN 


WM_KEYDOWN indicates that some key has been pressed, and the wParam gives the 
virtual key code. The only keys that SPY is interested in are the cursor keypad, so 
I made life simple for myself by calling the same DoScrol (Msg function that han- 
dles the scroll bars. I used a table, CsrScroll, to convert the virtual key codes into 
the appropriate parameters for DoScrol (Msg. 


WM_PAINT 


WM_PAINT is the big one, the message that says it’s finally time to paint our win- 
dow—or, more specifically, the client area of the window. Windows takes care of 
the title bar, menu bar, and scroll bars for us. There are two ways that we can get 
a WM_FPAINT message. The most common is when GetMessage discovers that 
there aren’t any other messages left for us. If any part of our window needs 
painting, we'll get a WM_PAINT message. We can also force an immediate WM_PAINT 
at any time by calling UpdateWindow as we do in the scrolling code. (UpdateWindow 
sends a WM_PAINT only if any part of the client area actually does need painting.) 
SPY’s window painting is done inside the PaintWindow function. 


WM_SIZE 


WM_S1IZE lets us know that the size of our window has changed. It's also sent when 
the window is first created, to tell us the initial size. SPY uses this information to 
recalculate the scroll bar ranges based on the current client area size. 


SpyOnAl lLWindows 


When SpyWndProc receives the WM_COMMAND/CMD_SPY message, it calls Spy- 
OnAl lWindows to scan all existing windows and gather up the information on 
them. We actually make two passes through all the windows here. The first loop 
counts the total number of windows so that we know how much memory to 
allocate for the INFOstructure that holds the window information. After allocat- 
ing this structure, we make a second loop through the windows to fill in the data 
for each. This could all be done in one pass, adjusting the memory size of the 
data structure as needed, but it’s a little faster to just calculate the needed size 
and allocate the correct size structure to begin with. 

For each window, SpyOnAl Windows calls SpyOnWindowto gather up the infor- 
mation about that window and its window class. This is done with with some 
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ordinary Windows functions, notably GetWindowWord, GetWindowLong, GetClass- 
Word, and GetClassLong. These functions extract various pieces of information 
from the actual window and class data structures that Windows maintains inter- 
nally. Unlike real-life spies, SPY doesn’t have to resort to any devious methods to 
get its information.. 


PaintWindow 


Finally we get to the point of the whole exercise, displaying something in our 
window. PaintWindow begins by calling the BeginPaint function, which lets Win- 
dows know that yes, we really are going to go ahead and paint the window. 
BeginPaint “validates” the entire window, that is, it clears out the update region 
to indicate that no further painting is required. It doesn’t throw out that update 
region completely, though. The intersection of the update region and our win- 
dow's clipping region becomes the clipping region used for painting, so any 
painting we do is clipped to the update region. 

This new clipping happens because BeginPaint creates a new device con- 
text for us and returns a handle to it. We save this handle in the hdcPaint variable 
for use in the actual painting. Any output you display in Windows is through 
some device context or another—all the output functions take a device context 
handle as a parameter. You can always get a device context for your window's 
client area by calling the Getoc function; you don’t have to wait for a WM_PAINT 
message. If you do, the clipping region for that device context would be unre- 
lated to any update region the window might have. However, the device context 
retrieved by BeginPaint specifically takes the update region into account. 

BeginPaint also fills in the PAINTSTRUCT structure that we pass as its second 
argument. This structure contains several pieces of information, in particular a 
rectangle called rcPaint, which is the smallest rectangle that encloses our up- 
date region, and tells us just where to start and stop painting. We can either use 
this information or disregard it—it's just an optimization to speed up painting. In 
SPY, we use the top and bottom of this rectangle to determine which lines to 
paint but we don’t bother worrying about the left and right edges. We just paint 
each line of text in its entirety and let Windows figure out which portion of the 
line needs to be displayed, based on the clipping region. 

After calling BeginPaint, we set the proper foreground and background 
colors for our text. The GetSysColor function that we use here returns the color 
values that the user set up with the Control Panel so SPY’s display will match the 
other windows on the screen. Back when we called RegisterClass, we specified 
that the background of our client area should always be erased using the 
COLOR_WINDOW color from Control Panel. We did this by setting the hbrBackground 
field in the window class structure. Here in the paint function, we set the back- 
ground color of the text itself to match. 
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Next, we take care of one detail that’s crucial to making the window scroll 
properly. Based on the current scroll bar positions, we calculate just where in 
the INFO structure to begin picking up data, and where in our window that data 
should be displayed. If our window were never scrolled, the first record in INFO 
would always be displayed at the top of our window. However, if the user has 
scrolled down one line, for instance, we must offset our display by one line. Simi- 
larly, if the user has scrolled horizontally, we have to offset our display accord- 
ingly. Note that the actual displacement is up to our code to determine. In SPY, I 
made one scroll bar increment equal to one character height or width, but the 
actual offsets are all in pixels. 

Finally, we loop through the INFO structure, and for each record we paint 
one line of text (the summary view) or several lines of text (the detail view). We 
stop the loop when we reach the bottom of the rcPaint rectangle or when we 
run out of entries in INFO. The INFO structure remains locked for the duration of 
this loop. We call GlobalLock before the loop and GlobalUnlock after the loop 
exits. 

To display each line on the screen, we can’t just do a printf as you might do 
in an ordinary C program. We have to call the Textout function provided by Win- 
dows. However, we can still take advantage of C’s formatting capability in a very 
convenient way. The Paint function that’s called for each line of text is the (al- 
most) exact equivalent of printf, except the actual output is sent to TextOut. We 
accomplish this trick by calling the vsprintf function within Paint to format the 
line in a memory buffer, and then pass that buffer as the string parameter to 
TextOut. vsprintf is really handy in situations like this. 


The Resource File: SPY .RC 


SPY’s resource file contains declarations for the resources that SPY uses. Three 
are read in during the Initialize function: an ICON statement, naming the icon 
file where I created SPY’s icon (using the ICONEDIT program supplied with the 
Windows software development kit); a STRINGTABLE statement listing the few text 
strings that I did make into resources; and a MENU statement, which sets up SPY's 
menu. Remember, it’s better to make all text messages into resources because 
that makes it easy to translate your application into other languages. 

Once you assign the menu command IDs (CMD_SPY, etc.) in a menu, you can 
fool around with the actual menu layout without changing your C code. Since 
the command IDs are not related to the actual menu position, you can move 
menu items around freely if you want to change the menu layout. Furthermore, 
you can create a complete menu structure and see how it looks in actual opera- 
tion long before you write any actual code to support those menu items. Any 
menu command ID codes that you haven't implemented will simply pass through 
your window function and be ignored. This is handy for prototyping menus. 
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You might also note the &character used in the menu strings. This specifies 
which character of a menu command is to be underlined, becoming the mne- 
monic shortcut character for that command. 

One last thing in spyY.RC is the DIALOG statement that defines the “About 
Spy ...” dialog box. This gives the location, size, and contents of each of the 
child windows that make up the dialog box. I actually built this definition using 
the Dialog Editor provided with the Windows SDK—that's a lot more convenient 
than trying to figure out all those coordinates manually! 


The Module Definition File: SPY .DEF 


Every Windows application has a .DEF file, used by the Windows linker LINK4, 
that specifies several pieces of information Windows needs to know about your 
application: the module name (which must match the name of your .EXE file), 
descriptions of the code and data segments your program uses, the size of the 
stack and local heap you want, and a list of the functions that your program 
“exports.” 

Each function that you are going to pass along to Windows to be called 
back, such as a window function or dialog function, must be listed in the EXPORTS 
list. Dialog functions, like AboutBox, must also be run through the MakeProcIn- 
stance function in your C code, as we do in the CMD_ABOUT case in SpyWndProc. 
Forgetting an EXPORTS entry or a MakeProcInstance call is one sure way to get 
your program to crash in very mysterious ways! The problem is that when Win- 
dows calls your function back, the DS register will contain the wrong value. 

The segment descriptions in the .DEF file are also important, but at least 
LINK4 will set up workable defaults if you leave one out. Since SPY is compiled in 
small model, we have only a single code segment and single data segment, and we 
declare them both to be MOVEABLE. It’s also possible to declare segments as FIXED, 
which can be handy for debugging. It's a good idea to avoid that if possible other- 
wise. 

Have you ever noticed that if you try to run a Windows application outside 
of Windows, it prints the message: This program requires Microsoft Windows? 
DOS doesn’t magically know that. A Windows .EXE file is actually two programs 
in one, a DOS program and a Windows program. The beginning of the .Ex€ file 
contains an ordinary DOS program, and that’s what will run if you try to run the 
. EXE from DOS. The actual Windows program is at the end of the .€XE file, past 
the portion that gets loaded when you run the .€xE from DOS. The Stu state- 
ment in the .DEF file gives the name of an ordinary DOS .€XE file which is to be 
included at the beginning of the Windows .EXE. The WINSTUB. EXE file named here 
is the program that prints: This program requires Microsoft Windows. You could 
put any program you wanted there, so a single .€xE could actually contain botha 
DOS version and a Windows version of a program. 
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If you've looked into any OS/2 programming, this discussion of the .DEF file may 
sound very familiar to you. That's because OS/2 applications use identical .DEF 
files, and in fact, the same new linker, as Windows applications. The technique 
of including both a DOS version and a new version of a program is exactly how 
OS/2’s “Family API” works. Windows and OS/2 share a number of other features, 
such as dynamic linking and relocatable memory management, and, of course, 
OS/2's Presentation Manager is a direct descendant of Windows. 

Besides being a link to the future, Windows is also an exciting system in its 
own right. It gives applications running on MS-DOS the kind of user interface 
the Macintosh has always been known for, and provides a great set of tools for a 
software developer to build quality applications. Programming for Windows is 
different from traditional application programming and takes some getting used 
to, but the results are worth it. I find most appealing about Windows the fact 
that it resolves the old conflict between ease of learning and convenience and 
utility for the experienced user. In a Windows application, you can have a pro- 
gram that’s easy to learn and powerful. 


Listing 9-1. SPY 


The files are: 


SPY MAKE file 

SPY.H Header file for .C and .RC 

SPY .C C source code 

SPY.RC Resource Compiler source code 

SPY.DEF Module definition file 

i ef SPY a a ee 


# Makefile for SPY.EXE 


spy.obj: spy.-c spy.h 
msc -AS -Gcsw —-Oas ~u -W3 -Zip $*; 


spy.ress spy.rc spy.ico spy.h 
re -r spy.rc 


spy.exes spy.obj spy.res spy.def 
Link4 spy, spy/align:16, spy/co, slibw, spy.def 
rc spy.res 
continued 


kkk kk RRR RRR RK SPY.H 

| ee 
/* SPY.H */ 

| i i 
#define MAXINT 32767 


#define MAXWORD 65535 


/* Menu command definitions */ 


#define CMD_ABOUT 
#define CMD_EXIT 
#define CMD_EXPAND 
#define CMD_SPY 


WN = 


/* String table ID numbers */ 


Hdefine IDS_CLASS 1 
Hdefine IODS_TITLE 2 


/* Dialog ID numbers */ 


#define ABOUTBOX 1 


| 
a SPY.C 
fe -- ee ee er er errr er er ee ee ee 
* Spy.c 
* Windows Spy Program 
* Public Domain 
* Written by Michael Geary 


continued 


Chapter 9: Inside Microsoft Windows 


eee Ke Keke keke RK KKK KR 


keekeke Ke Kk eK KKK Ke KH Ke 


271 


Section 2: Programming Tools and Techniques 


272 


+ ££ £ £+ €* + & & 


This program "spies" on all the windows that are 


currently open in your Windows session, and 


displays a window containing all the information 


it can find out about those windows. You can 
scroll through this window using either the 


mouse or keyboard to view the information about 


the various windows. The "New Spy Mission” 
menu item recaptures the latest information. 


#define LINT_ARGS 
#include <stdio.h> 
#include <stdarg.h> 
#include <windows.h> 
#include "spy.h'' 


/* 


+ + + + £ + & € + + € & &€ € &F FF + FF H HF FF HF 


* + £ &£ ££ + € & F 


The display for a single window looks Like this in 


collapsed mode: 


Cstyle] Window H {class} (L,T;R,8) "title" 


where [Estyle] is: [Child! Popup! Iconic] 


or like this in expanded mode: 


Cstyle] Window handle: H 
Class name: {class name} 
Window title: {title text} 
Parent window handle: H 


Class function, window function: H:H, H:H 
Class module handle, Window instance handle: H, H 
Class extra alloc, Window extra alloc: D, D 
Class style, Window style: H, H 

Menu handle: H -or- Control ID: 0 

Brush, Cursor, Icon handles: H, H, H 

Window rectangle: Left=D, Top=D, Right=D, Bottom=D 
Client rectangle: Left=D, Top=0, Right=D, Bottom=D 


{blank line} 


Total number of Lines for one window display: 13 


continued 


*/ 


#define LINES PER_WINDOW 13 


#define WINDOW_WIDTH 160 


Chapter 9: Inside Microsoft Windows 


/*x The INFO structure contains all the information we 


gather up about each window we are spying on. We 


allocate an array of INFO structures in the global 
heap, with one entry for each window in the 


system. 
*/ 


#define CLASSMAX 30 
#define TITLEMAX 50 


typedef struct { 
HWND winHWnd; 
char winClass(CLASSMAX]; 
HBRUSH winBkgdBrush; 
HCURSOR winCursor; 
HICON winlIcon; 
HANDLE winClassModule; 
WORD winWndExtra; 
WORD winClsExtra; 
WORD winClassStyle; 
FARPROC winClassProc; 
HANDLE winInstance; 
HWND winHWndParent; 
char winTit LeLTITLEMAX); 
WORD winControlID; 
FARPROC winWndProc; 
DWORD winStyle; 
RECT winWindowRect; 


RECT winClientRect; 
int winLevel: 
} INFO; 


typedef HANDLE HINFO; 
typedef INFO huge * LPINFO; 


/* 


/* 


Window handle 
Class name 

Bkgd brush handle 
Cursor handle 

Icon handle 

Class owner module 
Window extra data 
Class extra data 
Class style word 
Class window proc 
Window owner inst. 
Parent window 
Window title 

Ctrl ID/menu handle 
Window proc 

Window style bits 
Window rectangle 
Client rectangle 
Child window level 


INFO array handle 


*/ 


Far pointer to INFO */ 
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/* 


*/ 


The CsrScroll array is used for implementing 


keyboard scrolling. By looking up the keystroke 
in this array, we get the equivalent scroll bar 


message. 


Hdefine VK_MIN_ CURSOR VK_PRIOR 
fidefine VK_MAX_CURSOR VK_DOWN 


str 
c 
c 
+¢ 


AAA AAA A A 


/* 


HAN 
HIN 
LPI 
int 
BOO 
int 
int 
int 
int 
int 
int 
HDC 
cha 
cha 


uct { 

har csBar; /* Scroll bar this key triggers 
har csMsg; /* The scroll message for this key 
srScroll(] = ¢ 


SB_VERT, SB_PAGEUP } 
SB_VERT, SB_PAGEDOWN } 
SB_VERT, SB_BOTTOM } 
SB_VERT, SB_TOP } 
SB_HORZ, SB_LINEUP } 
SB_VERT, SB_LINEUP } 
SB_HORZ, SB_LINEDOWN } 
SB_VERT, SB_LINEDOWN } 


Static variables 


DLE hInstance; 

FO hInfo; 

NFO ILpInfo; 
nWindows; 

L bExpand = FALSE; 
nLinesEach = 1; 
nCharSizex; 
nCharSizey; 
nExtLeading; 
nPaintX; 
nPaintyY; 
hdcPaint; 

r szClass{[10); 

r szTitle(40]; 


& 
e 
Cd 
ce 
e 
’ 


8 


/* VK_PRIOR: PgUp 
/* VK_NEXT: PgDn 
/* VK_END: = End 

/* VK_HOME: Home 


/* VK_LEFT: left arrow 
up arrow 

/* VK_RIGHT: right arrow 
/* VK_DOWN: down arrow 


/* VK_UP: 


Our instance handle 
INFO global handle 
Far pointer to INFO 
Total # of windows 


Detailed view? 


1 or LINES_PER_WINDOW 
Char. width in pixels 


Char. height in pixels 
Extra pixels vertically 


X coordinate for 
Y coordinate for 
hOC for Paint to 
Our window class 
Our window title 


continued 
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/* Declare full templates for all our functions. Thi 
* gives us strong type checking on our functions. 
*/ 

BOOL FAR PASCAL AboutBox( HWND, unsigned, WORD, LONG 

void CountWindow( HWND ); 

int DoScrollMsg( HWND, int, WORD, int ); 

void HomeScrollBars( HWND, BOOL ); 

BOOL Initialize( HANDLE, int ); 

void cdecl Paint( char *, ... );3 

void PaintWindow( HWND ); 

void SetScrollBars( HWND ); 

void SetScrollBar1( HWND, int, int ); 

BOOL SpyOnAl lWindows( HWND ); 

void SpyOnWindow( HWND, int ); 
long FAR PASCAL SpyWndProc( HWND, WORD, WORD, LONG ); 

int PASCAL WinMain( HANDLE, HANDLE, LPSTR, int ) 

[xe - ee ee eke eer ee er er er er meer em rm mmr en ere 


/* Dialog function for the About box. 
Since this is a simple box with only one button, 


s 


3 


WM_COMMAND is assumed to be a click on that button 


(the command number is not checked). 
*/ 


BOOL FAR AboutBox( hDlg, wMsg, wParam, \Param ) 


HWND hDlg; /* Window handle 

unsigned wMsg; /* Message number 

WORD wParam; /* Word parameter 

LONG lParam; /* Long parameter 
{ 


switch( wMsg ) { 


case WM_COMMAND: 
EndDialog( hDlg, TRUE ); 
return TRUE; 


case WM_INITDIALOG: 
return TRUE; 
} 
return FALSE; 
} 


continued 
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/x Count a window for the size calculation. Loops 

* through its children recursively and counts them 
* as well. 

*/ 


void CountWindow( hWnd ) 
HWND hWnd; /*x Window handle to count */ 


HWND hWndChild; /* Child window for loop = */ 


/* Count this window */ 
++nWindows; 


/* Loop through children and count them */ 
for ( 
hWndChild = GetWindow( hWnd, GW_CHILD ); 
hWndChild; 
hWndChild = GetWindow( hWndChild, GW_HWNDNEXT ) 
¢{ 
CountWindow( hWndChild ); 


} 
} 
| i rr «/ 
/* Process a scroll bar message. Calculates the 
* distance to scroll based on the scroll bar range 
* and the message code. Limits the scroll to the 
* actual range of the scroll bar. Sets the new 
* scroll bar thumb position and scrolls the window 
* by the necessary amount. Note that the scroll bar 
* ranges are set in terms of number of characters, 
* while the window scrolling is done by a number of 
* pixels. Returns the distance scrolled in chars. 
*/ 


int DoScrollMsg( hWnd, nBar, wCode, nThumb ) 


HWND hWnd; /*x Window handle to scroll */ 

int nBar; /* SB_HORZ or SB_VERT */ 

WORD wCode; /* Scroll bar message code */ 

int nThumb; /* SB_THUMBPOSITION param. */ 
continued 


int nOld; /* Old scroll ba 
int nDiff; /* Scroll bar ch 
int nMin; /* Scroll bar ra 
int nMax; /* Scroll bar ra 
int nPageSize; /* Window height 
RECT rect; /* Window client 


/* Get old scroll position and scroll ra 
nOld = GetScrollPos¢ hWnd, nBar ); 
GetScrollRange( hWnd, nBar, &nMin, &nMax 


/* Quit if no scrolling (see SetScrollBa 
if€ nMax == MAXINT ) 
return OQ; 


/* Calculate horizontal or vertical page 
GetClientRect( hWnd, &rect ); 
if(€ nBar == SB_HORZ ) 


nPageSize = (rect.right - rect.left) / 
else 
nPageSize = (rect.bottom - rect.top) / 


/* Select scroll amount, based on scroll 
switch( wlode ) { 


case SB_LINEUP: 
ndiff = -1; 
break; 


case SB_LINEDOWN: 
nDiff = 1; 
break; 


case SB_PAGEUP: 
nDiff = -nPageSize; 
break; 


case SB_PAGEDOWN: 
nDiff = nPageSize; 
break; 


case SB_THUMBPOSITION: 
continued 
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r position */ 


ange */ 

nge min. */ 

nge max. */ 
in chars */ 


rectangle */ 
nge */ 
); 
rs) */ 


size */ 


nCharSizex; 
nCharSizeyY; 


message */ 
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nDiff = nThumb - nOld; 
break; 


case SB_TOP: 
nDiff = -30000; /* A kludge but it works... */ 
break; 


case SB_BOTTOM: 
nDiff = 30000; 
break; 


default: 
return O;3 


/* Limit scroll destination to nMin..nMax */ 
if€ nDiff < nMin - nOld ) 
nDiff = nMin - nOld; 


if( nDiff > nMax - nOld ) 
nDiff = nMax - nOld; 


if( nDdDiff == 0) 
return 0; /* Return if net effect is nothing */ 


/* Now we can set the new scroll bar position */ 
SetScrollPos(¢ hWnd, nBar, nOld + nDiff, TRUE ); 


/* Scroll the actual window contents */ 
Scrol LWindow(¢ 
hWnd, 
nBar == SB_HORZ ? -nDiff*nCharSizex : O, 
nBar == SB_HORZ ? O : -nDiff*nCharSizey, 
NULL, 
NULL 
); 


/* Force immediate update for cleaner appearance */ 
UpdateWindow( hWnd ); 


return nDiff; 
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/* Set both scroll bars to the home position (0) 
*/ 


void HomeScrollBars( hWnd, bRedraw ) 
HWND hWnd; /* Window handle */ 
BOOL bRedraw; /* Redraw scroll bars? */ 


SetScrollPos( hWnd, SB_HORZ, 0, bRedraw ); 
SetScrollPos( hWnd, SB_VERT, 0, bRedraw ); 


/* Initialize the application. Some of the 

* initialization is different depending on whether 
* this is the first instance or a subsequent 

* instance. For example, we register our window 

* class only in the first instance. Returns TRUE if 
* initialization succeeded, FALSE if failed. 


BOOL Initialize( hPrevInst, nCmdShow ) 


HANDLE hPreviInst; /* Prev. instance or 0 */ 
int nCmdShow; /* ShowWindow parameter */ 
{ 
WNDCLASS Class; /* RegisterClass structure */ 
HWND hWnd; /* Our window handle */ 
HDC hoc; /* Temp display context */ 
TEXTMETRIC Metrics; /* System font metrics */ 
int nScreenx; /* Screen width in pixels */ 
int nScreeny; /* Screen height in pixels */ 


nScreenX = GetSystemMetrics( SM_CXSCREEN ); 
nScreenY = GetSystemMetrics( SM_CYSCREEN ); 


if( ! hPrevInst ) ¢ 
/* Initialization for first instance only */ 


/* Load strings from resource file--really, all 
* message strings should be loaded here--we just 
* load a couple as an example. */ 

continued 


279 


Section 2: Programming Tools and Techniques 


280 


LoadString ( 

hInstance, IDS_CLASS, szClass, sizeof(szClass) 
); 
LoadString(¢ 

hInstance, IDS_TITLE, szTitle, sizeof (szTitle) 
3 


/* Register our window class */ 


Class.style = CS_HREDRAW | CS_VREDRAW; 
Class.lpfnWndProc = SpyWndProc; 

Class.cbClsExtra = 0; 

Class.cbWndExtra = Q; 

Class.hInstance = hInstance; 

Class.hIcon = LoadIcon(hInstance,szClass); 
Class.hCursor = LoadCursor (NULL, IDC_ARROW); 
Class.hbrBackground = COLOR_WINDOW + 1; 

Class. lpszMenuName = szClass; 


Class. lpszClassName = szClass; 
if€ ! RegisterClass(&Class) ) 
return FALSE; 


} else { 
/* Initialization for subsequent instances only */ 


/* Copy data from previous instance */ 
GetInstanceData( 

hPreviInst, szClass, sizeof(szClass) 
); 
Get InstanceData( 

hPrevinst, szTitle, sizeof (szTitle) 
a; / 

} \ 


/* Initialization for every instance */ 


/* Allocate an empty INFO structure */ 
hInfo = GlobalAlloc( GMEM_MOVEABLE, 1L ); 
if€ ! hInfo ) 

return FALSE; 


/* Create our tiled window, don't display it yet */ 
hWnd = CreateWindow( 
continued 
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szClass, /* Class name */ 
szTitle, /* Window title */ 
WS_OVERLAPPEDWINDOW ! /* Window style x/ 
WS_HSCROLL ! WS_VSCROLL, 
nScreenx * 1 - 20, /* X: 5% from left */ 
nScreeny * 1 - 10, /* Y 10% from top */ 
nScreenxX * 9 - 10, /* nWidth: 90% «/ 
nScreenyY * 7 - 10, /* nHeight: 70% x/ 
NULL, /* No parent hWnd */ 
NULL, /* Menu handle */ 
hInstance, /* Owner instance handle */ 
NULL /* WM_CREATE parameter  */ 
); 


/* Initialize scroll bars */ 
HomeScrollBars( hWnd, FALSE ); 


/* Calculate character size for system font */ 
hOC = GetDCC hWnd ); 
GetTextMetrics( hDC, &Metrics ); 
ReleaseDC( hWnd, hDC ); 
nExtLeading = Metrics.tmExternalLeading; 
nCharSizeX = Metrics.tmMaxCharWidth; 
nCharSizeY = 
Metrics.tmHeight + Metrics.tmExternalLeading; 


/* Make the window visible before grabbing spy info, 
* so it's included */ 
ShowWindow( hWnd, nCmdShow ); 


/* Post a message to ourself to trigger the first 
* spy information display */ 
PostMessage( hWnd, WM_COMMAND, CMD_SPY, OL ); 


return TRUE; 


Format and paint a line of text. The parameters 

are the same as for an ordinary printf call, a 

format string followed by a variable number of 

arguments to be formatted. We use the vsprintf 
continued 
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function to format the final string to be 
painted. The global variables nPaintX and nPaintY 
tell where to paint the Line. We increment 
nPaintY to the next line after painting. Note the 
cdecl' declaration. This forces this function to 
use the standard C calling sequence, which is 
necessary with a variable number of parameters. 


+ + + £ ££ & 


*/ 


void cdecl Paint( szFormat /* , ... */ ) 


char * szFormat; /* vsprintf format string */ 
{ 

va_list pArgs; /* vsprintf parameters xf 

int nLength; /* Formatted string length */ 

char Buf(160); /* Temp buffer */ 


va_start( pArgs, szFormat ); 
nlength = vsprintf( Buf, szFormat, pArgs ); 
va_end( pArgs ); 


TextOut ¢ 
hdcPaint, 
nPaintX, 
nPaintY+nExtLeading, 
Buf, 
nLength 


~ 
* 


Paints our window or any portion of it that needs 
painting. The BeginPaint call sets up a structure 
that tells us what rectangle of the window to 
paint, along with other information for the 
painting process. First, erase the background 
area if necessary. Then, calculate the index into 
the INFO array to start with, based on the 
painting rectangle and the scroll bar position, and 
lock down the INFO. Finally, loop through the 
INFO array, painting the text for each entry. 
continued 
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* Quit when we run out of entries or hit the bottom 
* of the paint rectangle. 


*/ 


void PaintWindow( hWnd ) 


HWND hWnd; 
{ 

PAINTSTRUCT ps; 

DWORD rgbOldText; 
DWORD rgbOLdBkgd; 
int nWin; 

int X; 

int Y; 

PSTR pTypeName; 


/* Set up paint structure, store HDC for Paint() */ 


/* 
/* 


Window handle to paint 


Painting information 
Old text color 

Old background color 
Index into INFO array 
X position (temp) 

Y position (temp) 

Ptr to style string 


hdcPaint = BeginPaint( hWnd, &ps ); 


/* Set up painting colors and save old values */ 


rgbOldBkgd = 
SetBkColor( 
hdcPaint, 


GetSysColor(COLOR_WINDOW) 


; 
rgbOldText = 
SetTextColor (¢ 
hdcPaint, 


GetSysColor(COLOR_WINDOWTEXT) 


); 


/* Calculate horizontal paint position, based on 
* the scroll bar position */ 
X = (1 - GetScrollPos( hWnd, SB_HORZ ) ) 


* nCharSizex; 


/*x Calculate index into INFO array and vertical paint 
* position, based on scroll bar position and top of 


* painting rectangle */ 


Y = GetScrollPos( hWnd, SB_VERT ); 
nWin = ( ps.rcPaint.top - nCharSizeY + Y ) 


- nLinesEach; 


nPaintY = € nWin * nLinesEach - Y ) 


* nCharSizeyY; 
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/* Lock down INFO array and set lpInfo pointing to 
* first entry to paint */ 

lpInfo = CLPINFO)GLobalLock( hInfo ); 

lpInfo += nWin; 


/* Loop through INFO entries, painting each one until 
* we run out of entries or until we are past the 
* bottom of the paint rectangle. We don't worry 
* much about painting outside the rectangle-- 
* Windows will clip for us. */ 
while¢ 
nWin < nWindows && 
nPaintY < ps.rcPaint.bottom 
¢{ 


/* Set X position and indent child windows */ 
nPaintX = 
X + 
( LpInfo->winLlevel * nCharSizex 
x (bExpand 7? 4 : 2) ); 


/* Set up pTypeName for window style */ 

if€ LpInfo->winStyle & WS_CHILD ) 
pTypeName = "Child window": 

else if(€ lpInfo->winStyle & WS_ICONIC ) 
pTypeName = "Iconic window"; 

else if(€ LpInfo->winStyle & WS_POPUP ) 
pTypeName = "Popup window''; 

else 
pTypeName = "Window's: 


if€ ! bExpand ) { 


/x Paint the summary view */ 

Paint ¢ 
"%s Z04X {4Fs} (hd, Adjud,4d) \"'ZFs\'", 
pTypeName, 
LpInfo->winHWnd, 
LpInfo->winClass, 
LpInfo->winWindowRect. left, 
LpInfo->winWindowRect.top, 
LpInfo->winWindowRect.right, 
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LpInfo->winWindowRect bottom, 
LpInfo->winTitle 
); 


else { 


/* Paint the detail view, window handle first */ 
Paint ¢ 

"Zs handle: %O04X"', 

pTypeName, 

lpInfo->winHWnd 
); 


/* Paint the rest of the info, indented more */ 
nPaintX += nCharSizex * 2; 


Paint( "Class name: %Fs", lpInfo->winClass ); 
Paint( "Window title: %Fs", lpInfo->winTitle ); 
Paint ¢ 
"Parent window handle: %04X", 
LpInfo->winHWndParent 
); 
Paint ¢ 
"Class function, Window function: 4p, 4p", 
LpInfo->winClassProc, 
LpInfo->winWndProc 
5 
Paint ¢ 
"Class module handle, Window instance handle: \ 
%04X"', 
LpInfo->winClassModule, 
LpInfo->winInstance 
); 
Paint ¢ 
"Class extra alloc, Window extra alloc: \ 


ad, 2d", 


LpInfo->winClsExtra, 
LpInfo->winWndExtra 
3 
Paint ¢ 
"Class style, Window style: %04X, ZO8LXx", 
lLpInfo->winClassStyle, 
LpInfo->winStyle 
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3 
Paint ¢ 
lpInfo->winStyle & WS CHILD 
? "Control ID: %d" 
: "Menu handle: %04X", 
lpInfo->winControlID 
3 
Paint ¢ 
"Brush, Cursor, Icon handles: \ 
404X, #04X, X404X"', 
LpInfo->winBkgdBrush, 
LpInfo->winCursor, 
lpInfo->winIcon 
); 
Paint ¢ 
"Window rectangle: \ 

Left=44d, Top=44d, Right=%4d, Bottom=%4d'"', 
LpInfo-~>winWindowRect. left, 
LpInfo->winWindowRect.top, 
LpInfo->winWindowRect.right, 
LpInfo->winWindowRect.bottom 

5 
Paint ¢ 
"Client rectangle: \ 

Left=%4d, Top=4%4d, Right=44d, Bottom=%4d"', 
LpInfo->winClientRect.left, 
LpInfo~>winClientRect.top, 
LpInfo->winClientRect.right, 
LpInfo->winClientRect.bottom 

); 


/*x Make a blank line--it's already erased, 
* so just increment Y */ 
nPaintY += nCharSizey; 
} 


/* Increment to next INFO entry */ 
++nWin; 
++lpInfo; 


/*x Unlock the INFO array */ 
GlobalUnlock( hInfo ); 
continued 


286 


~ 
+ + ££ &£ © £© © €& &* HH & 


+ 
~ 


Chapter 9: Inside Microsoft Windows 


/* Restore old colors */ 
SetBkColor( hdcPaint, rgbOldBkgd ); 
SetTextColor( hdcPaint, rgbOldText ); 


/* Tell Windows we're done painting */ 
EndPaint( hWnd, &ps ); 


Set horizontal and vertical scroll bars, based on 
the window size and the number of INFO entries. 
The scroll bar ranges are set to give a total 
width of WINDOW_WIDTH and a total height equal to 
the number of Lines of information available. For 
example, if there are 130 Lines of information and 
the window height is 10 characters, the vertical 
scroll range is set to 120 (130 - 10). This lets 
you scroll through everything and still have a 
full window of information at the bottom. (Unlike, 
say, Windows Write, in which scrolling to the 
bottom gives a blank screen.) 


void SetScrollBars¢ hWnd ) 


HWND hWnd; /* Window handle */ 
RECT rect: /* Window client rectangle */ 
GetClientRect( hWnd, &rect ); 


SetScrol LBart ¢ 


hWnd, SB_HORZ, 
WINDOW_WIDTH - rect.right / nCharSizex 


3 


SetScrollBari1 ¢ 


hWnd, SB_VERT, 
nWindows * nLinesEach - rect.bottom / nCharSizeyY 


3 
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Set one scroll bar's maximum range. We always set 
the minimum to zero, although Windows allows other 
values. There is one case we handle specially. If 
you set a scroll bar range to minimum==maximum 
(maximum = zero for us), Windows does not actually 
set the range, but instead turns off the scroll 
bar completely, changing the window style by 
turning off the WS_HSCROLL or WS_VSCROLL bit. For 
example, this is how the MS-DOS Executive makes 
its scroll bars appear and disappear. This 
behavior is fine if you take it into account in 
your programming in two ways. First, whenever you 
do a GetScrollRange you must first check the window 
style to see if that scroll bar still exists, 
because you will *not* get the correct answer from 
GetScrollRange if it has been removed. Second, you 
must be prepared to get some extra WM_SIZE 
messages, because your client area changes size 
when the scroll bars appear and disappear. This 
can cause some sloppy looking screen painting. We 
take a different approach, always keeping the 
scroll bars visible. If the scroll bar range needs 
to be set to zero, we set it to MAXINT instead so 
the bar remains visible. Then, DoScrollMessage 
checks for this case and returns without scrolling. 


void SetScrollBar1(¢ hWnd, nBar, nMax ) 


HWND hWnd; /* Window handle x/ 
int nBar; /* SB_HORZ or SB_VERT */ 
int nMax; /* New maximum range value */ 
int nOldMin; /* Previous min value (0) */ 
int nOldMax; /* Previous max value */ 


/* Check for a negative or zero range and set our 


* special case flag. Also, set the thumb position 
* to zero in this case. */ 


if€ nMax <= 0) € 


nMax = MAXINT; 
DoScrollMsg( hWnd, nBar, SB_THUMBPOSITION, O ); 
continued 
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/* Get previous range, set it if it has changed */ 
GetScrollRange( hWnd, nBar, &nOLdMin, &nOldMax ); 
if(@ nMax != nOldMax ) 

SetScrollRange( hWnd, nBar, O, nMax, TRUE ): 


Loop through all windows in the system and gather 
up information for the INFO structure for each. We 
actually loop through them twice: first, to 
simply count them so we can allocate global memory 
for the INFO structure, and again to actually fill 
in the structure. After gathering up the 
information, we invalidate our window, which will 
cause a WM_PAINT message to be posted, so it will 
get repainted. 


BOOL SpyOnAllWindows( hWnd ) 


HWND hWnd; /* Our window handle */ 
HWND hWndTop; /* Window handle for loop */ 


/* Count up the number of windows */ 
nWindows = 0; 


for( 
hWndTop = GetWindow( hWnd, GW_HWNDFIRST ); 
hWndTop; 
hWndTop = GetWindow( hWndTop, GW_HWNDNEXT ) 
¢ 
CountWindow( hWndTop ); 
} 


/* Allocate memory, complain if we couldn't get it */ 
hInfo = 
GlobalReAl Loc (¢ 
hInfo, 
CDWORD) nWindows*sizeof (INFO), 
GMEM_MOVEABLE 
3 
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if€ ! hInfo ) ¢€ 
nWindows = Q; 
GlobalDiscard( hInfo ); 
MessageBox ( 
GetActiveWindow(), 
"Insufficient memory! !", 
NULL, 
MB_OK | MB_ICONHAND 
3 
PostQuitMessage( 0 ); 
return FALSE; 


/* Lock down memory and fill it in, then unlock */ 
lpInfo = (LPINFO)GlobalLock( hInfo ); 


for( 
hWndTop = GetWindow( hWnd, GW_HWNDFIRST ); 
hWndTop; 
hWndTop = GetWindow( hWndTop, GW_HWNDNEXT ) 
¢ 
SpyOnWindow( hWndTop, O ); 
} 


GlobalUnlock( hInfo ); 


/* Set scroll bars based on new window count */ 
SetScrollBars( hWnd ); 
HomeScrollBars( hWnd, TRUE ); 


/* Invalidate our window so it will be repainted */ 
InvalidateRect( hWnd, NULL, TRUE ); 


return TRUE; 


/* Gather up the information for a single window and 
store it in the INFO array entry pointed to by 
lpInfo. Increment lpInfo to the next entry 
afterward. Called once for each window. 

*/ 
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void SpyOnWindow( hWnd, nLevel ) 


HWND hWnd; /* Window handle */ 

int nLevel; /* Child window level */ 
{ 

HWND hWndChild; /* Child window for loop = */ 


/* Gather up this window's information */ 
LpInfo->winHWnd = hWnd; 
GetClassName( hWnd, lpInfo->winClass, CLASSMAX ); 
lpInfo->winClass[ CLASSMAX - 1 ] = 0; 
lpInfo->winInstance = 

GetWindowWord( hWnd, GWW_HINSTANCE ); 
LpInfo->winHWndParent = GetParent( hWnd ); 
GetWindowText( hWnd, lLpInfo->winTitle, TITLEMAX ); 
LpInfo->winTitlel TITLEMAX - 1 ] = 0; 
LpInfo->winControlID = 

GetWindowWord( hWnd, GWW_ID ); 
LpInfo->winWndProc = 

CFARPROC)GetWindowLong( hWnd, GWL_WNDPROC ); 
LpInfo->winStyle = 

GetWindowLong( hWnd, GWL_STYLE ); 
GetClientRect( hWnd, &lpInfo->winClientRect ); 
GetWindowRect( hWnd, &lpInfo->winWindowRect ); 
lLpInfo->winLevel = nLevel; 


/* Gather up class information */ 
LpInfo->winBkgdBrush = 

GetClassWord( hWnd, GCW_HBRBACKGROUND ); 
LpInfo->winCursor = 

GetClassWord( hWnd, GCW_HCURSOR ); 
LpInfo->winIcon = 

GetClassWord( hWnd, GCW_HICON ); 
lpInfo->winClassModule = 

GetClassWord( hWnd, GCW_HMODULE ); 
LpInfo->winWndExtra = 

GetClassWord( hWnd, GCW_CBWNDEXTRA ); 
LpInfo->winClsExtra = 

GetClassWord( hWnd, GCW_CBCLSEXTRA ); 
lpInfo->winClassStyle = 

GetClassWord( hWnd, GCW_STYLE ); 
LpInfo->winClassProc = 

C(FARPROC)GetClassLong( hWnd, GCL_WNDPROC ); 
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/* Move on to next entry in table */ 
++lpInfo; 


/* Now spy on children recursively */ 
for(¢ 
hWndChild = GetWindow( hWnd, GW_CHILD ); 
hWndChild; 
hWndChild = GetWindow( hWndChild, GW_HWNDNEXT ) 
¢ 
SpyOnWindow( hWndChild, nlLevel + 1 ); 


/* Window function for our main window. All messages 

* for our window are sent to this function. For 

* messages that we do not handle here, we call 

* DefWindowProc, which performs Windows’ default 
processing for a message. 

*/ 


long FAR PASCAL SpyWndProc( 
hWnd, wMsg, wParam, lParam 


) 
HWND hWnd; /* Window handle 
WORD wMsg; /* Message number 
WORD wParam; /* Word parameter 
LONG lParam; /* Long parameter 
{ 
RECT rect; /* Temp rectangle 
FARPROC LpProc; /* AboutBox ProcInstance 


switch( wMsg ) ¢ 


/* Menu command message - process the command */ 
case WM_COMMAND: 
if( LOWORD(LParam) ) 
break; /* not a command */ 
switch( wParam ) ¢ 
case CMD_ABOUT: 
lpProc = 
MakeProcInstance( 
continued 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
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(FARPROC) About Box, 
hInstance 
); 
if€ ! lpProc ) 
return OL; 
DialogBox(¢ 
hInstance, 
MAKE INTRESOURCE CABOUTBOX), 
hWnd, 
lpProc 
3 
FreeProcInstance( lpProc ); 
return OL; 
case CMD_EXIT: 
DestroyWindow( hWnd ); 
return OL; 
case CMD_EXPAND: 
bExpand = ! bExpand; 
nLinesEach = 
( bExpand ? LINES _PER_WINDOW : 1); 
CheckMenulItem( 
GetMenu( hWnd ), 
CMD_EXPAND, 
bExpand ? MF_CHECKED : MF_UNCHECKED 
5 
InvalidateRect( hWnd, NULL, TRUE ); 
HomeScrollBars( hWnd, FALSE ); 
SetScrollBars(€ hWnd ); 
return OL; 
case CMD_SPY: 
SpyOnALlLWindows( hWnd ); 
return OL; 
} 
break; 


/* Destroy-window message - quit the application */ 
case WM_DESTROY: 

PostQuitMessage( 0 ); 

return OL; 


/* Horizontal scroll message--scroll the window */ 
case WM_HSCROLL: 
DoScrol lMsg¢ 


continued 
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hWnd, SB_HORZ, 
wParam, Cint) lParam 
); 
return OL; 


/* Key-down message--handle cursor keys, ignore 
* other keys */ 
case WM_KEYDOWN: 
if¢ 
wParam >= VK_MIN_CURSOR && 
wParam <= VK_MAX_CURSOR 


¢{ 
DoScroLllMsg(¢ 
hWnd, 
CsrScroll{£ wParam--VK_MIN_CURSOR J].csBar, 
CsrScrollC€ wParam--VK_MIN_CURSOR ].csMsgqg, 
0 
); 
} 


return OL; 


/* Paint message--repaint window as needed */ 
case WM_PAINT: 

PaintWindow( hWnd ); 

return OL; 


/* Size message--recalculate our scroll bars */ 
case WM SIZE: 

SetScrollBars( hWnd ); 

return OL; 


/* Vertical scroll message--scroll the window */ 
case WM_VSCROLL: 
DoScrol LMsg(¢ 
hWnd, SB_VERT, 
wParam, Cint) lParam 
3 
return OL; 


/* ALL other messages go to DefWindowProc */ 
return DefWindowProc( hWnd, wMsg, wParam, lParam ); 
} 


continued 
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/* Application main program. Not much is done here-- 
we just initialize the application, putting up our 


window, and then go into the message dispatching 
loop that every Windows application has. 
*/ 


int PASCAL WinMain(¢ 
hInst, hPreviInst, lpszCmdLine, nCmdShow 

) 
HANDLE hInst; /* Our instance handle 
HANDLE hPrevInst; /* Previous instance 
LPSTR lpszCmdLine;/* Command line pointer 
int nCmdShow; /* ShowWindow parameter 


MSG msg; /* Message structure */ 


/* Save our instance handle in static variable */ 
hInstance = hInst; 


/* Initialize application, quit if any errors */ 
if€ ! Initialize( hPrevInst, nCmdShow ) ) 
return 1; 


/* Main message processing loop. Get each message, 
* then translate keyboard messages, and finally 
* dispatch each message to its window function. */ 
while( GetMessage( &msg, NULL, 0, 0) ) ¢ 
TranslateMessage( &msg ); 
DispatchMessage( &msg ); 
} 


return msg.wParam; 


continued 


*/ 
*/ 
*/ 
*/ 


295 


Section 2: Programming Tools and Techniques 


296 


/* Spy.rc - resource file for SPY.EXE */ 


#include <style.h> 
finclude ''spy.h" 


| a */ 
Spy! ICON spy.ico 
| a xf 
STRINGTABLE 
BEGIN 

IDS_CLASS, "Spy !'' 

IDS_TITLE, "Spy on Windows!" 
END 
| a ee x/ 
Spy! MENU 
BEGIN 


POPUP "&Spy' 

BEGIN 
MENUITEM "'&New Spy Mission", CMD_SPY 
MENUITEM SEPARATOR 


MENUITEM "Show &Detail", CMD_EXPAND 
MENUITEM SEPARATOR 
MENUITEM "E&xit", CMD_EXIT 
MENUITEM "A&bout Spy...", CMD_ABOUT 
END 
END 
| a x/ 


ABOUTBOX DIALOG 25, 25, 180, 85 
STYLE WS_DLGFRAME ; WS_POPUP 
BEGIN 
CTEXT "Spy" -1, O, 5,180, 8 
continued 
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ICON "Spy!!! -1, 13, 25, 0, O 
CTEXT "Windows espionage program -1, 0, 16,180, 8 
CTEXT "Version 1.1" -1, 58, 38, 64, 8 
CTEXT "Written by Michael Geary" -1, 0, 50,180, 8 


DEFPUSHBUTTON "Ok"" IDOK, 74, 67, 32, 14, WS_GROUP 


END 

| i eo */ 

Re kK KKK KKK KKK SPY. DEF kKeEKkK KKK KKK KKK KK 
NAME Spy 


DESCRIPTION ‘Windows Espionage’ 
STUB "WINSTUB. EXE‘ 


CODE MOVEABLE 
DATA MOVEABLE MULTIPLE 


HEAPSIZE 1024 
STACKSIZE 4096 


EXPORTS 
About Box a1 
SpyWndProc a2 
Reading List 


Geary, M. 1987. Microsoft Windows 2.0. Microsoft Systems Journal (July). 


. 1987. Spying on windows. Byte Extra Edition: Inside the IBM PCs 12, no. 
12. 


. 1988. Converting Windows applications for Microsoft's OS/2 Presenta- 
tion Manager. Microsoft Systems Journal (January). 


Grayson, P. 1987. Windows of opportunity. PC Tech Journal (February). 


Petzold, C. 1986. A step-by-step guide to building your first windows application. 
Microsoft Systems Journal (December). 
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. 1988. Programming Windows. Redmond, Washington: Microsoft Press. 


Wong, W. 1987. Program interfacing to Microsoft Windows. Micro/Systems Jour- 
nal (series starting January/February). 


Michael Geary is the principal author of Gupta Technologies’ SQLWindows, an 
interactive application development system for SOL database applications running 
under MS Windows and the OS/2 Presentation Manager. He has written articles on MS 
Windows programming for Byte and Microsoft Systems Journal and is the author of 
several popular windows utilities, including SPY, Tiler, and Termite (a utility that inte- 
grates Notepad and terminal). He is also a technical advisor in Microsoft online sup- 
port forums. 
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4 Adding Power to MS-DOS Programming 
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WORKING WITH THE 
HARDWARE INTERFACE 


"Die huge existing base of MS-DOS machines offers a stable, lucrative market 
for those who can extract the maximum speed from RAM memory, board-level 
registers, and the clever choice of MS-DOS services. The Expanded Memory Sys- 
tem, the serial port, the Enhanced Graphics Adapter, and many other devices 
connect to the main bus through the slots, known as the I/O channel. Such a 
unifying point in common highlights the contrast in style with which the au- 
thors treat their topics. The five essays in this section focus on control of the 
hardware environment. 


Developing MS-DOS Device Drivers 


This section's first essay, by Walter Dixon, explains the construction of device 
drivers and their interface with the DOS kernel and loader. We see how the Sys- 
tem File Table, file handles, Device Control Blocks, Current Directory Structure, 
Program Segment Prefix, and other data structures and workings come into 
play during the process of loading and using a device driver. 


Writing a SOUND Device Driver 


Walter Dixon builds on his previous essay and presents a full-blown device 
driver that turns the PC into a musical instrument, parallel to the PLAY state- 
ment in BASIC. The SOUND driver can be played from the MS-DOS user inter- 


face or from within an application, the difference being only in writing to the 
driver. 


Programming the Enhanced Graphics Adapter 


This essay by Andrew Dumke explains the new latching and bit-map design of 
this popular display interface. Then he presents a fast dot-drawing program in 
C, a fast line-drawing algorithm, and ways to read EGA memory, perform Bool- 
ean operations on its bit maps, and more. 
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Programming the Serial Port with C 


Naba Barkakati reviews the basics of serial communications and explains the 
hardware of the serial port. He then discusses error-checking, flow control, 
buffers, serial interrupts, and use of a circular buffer, and ends with a complete 
communications program in C. 


Understanding Expanded Memory Systems 


Ray Duncan explains the rudiments of the bank-switching scheme for EMS, 
EEMS, and EMS 4.0 and how to test for the Enhanced Memory Manager. He sum- 
marizes relevant functions and presents an eight-step strategy for writing appli- 
cations for Enhanced Memory Systems. 


jai stakingly dissssembled. the rel : i 
i 8.of DOS to oe: you ene a 


mi and handled byt the driver. = | : . | 


Developing MS-DOS 
Device Drivers 


Walter Dixon 


Bach MS-DOS application program calls upon DOS to perform services such as 
opening or writing to a file. Some of these services greatly simplify the task of 
program development; for example, an application asks DOS to write 10 charac- 
ters to a printer the same way it would ask that those characters be sent to a disk 
file. This feature is known as device-independent I/O, a very important service 
because it frees the application from dealing with the hardware details of differ- 
ent devices. 

What we call DOS really is a number of distinct components: the kernel, 
device drivers, a user interface, and kernel enhancements. (See Essay 1, A 
Guided Tour inside MS-DOS, by Harry Henderson, for an overview of the 
MS-DOS components and their interfaces.) The kernel is a basic set of services, 
most of which are I/O related. Included in the kernel is support for the file sys- 
tem and device-independent I/O. Device drivers are short pieces of code that 
help DOS deal with hardware such as disks, keyboards, and consoles. Drivers 
worry about the hardware which controls individual devices and hide these 
details from the kernel. Kernel enhancements extend the functionality of the 
kernel. They are needed in special circumstances and should function transpar- 
ently when they are invoked; for example, SHARE.EXE is a kernel enhancement 
which supports file sharing. 

I obtained material for this paper by disassembling PC-DOS version 3.10. As 
far as I know, much of this information has not been previously documented. 
Disassembling a complex program such as DOS without access to any of the de- 
sign documentation is a difficult task. I cannot guarantee that the descriptions 
are completely accurate or that the operating system design will not change in 
the future. If you make use of any of this material, you do so at your own risk. 

Documentation on the Application/Kernel and Kernel/Driver interface is 
reasonably good, but the actions of the DOS kernel remain somewhat of a mys- 
tery. It loads and locates device drivers and transforms high-level application re- 
quests such as read and write into device driver operations. Values in the kernel 
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I/O data structures affect the way the kernel transforms requests. A side effect 
of these transformations is that the kernel sends status, flush, and nondestruc- 
tive read requests to various drivers. 

The design of the DOS kernel limits the actions of both drivers and applica- 
tions. Significant portions of the kernel are nonreentrant and once the kernel 
begins to execute a nonreentrant section of code, it must complete that section 
before it can safely process another request. Some of the more subtle implica- 
tions of this architectural will enable you to bend some of the published rules 
for writing drivers and create your own background programs like PRINT.COM 
which can share the processor with other tasks. 

This essay concentrates on the transformation process and its side effects. 
Some exposure to device drivers is necessary if you want to completely under- 
stand the interaction of the DOS kernel with drivers. Even if you do not plan to 
write a driver, you may find this material interesting. DOS is a significant operat- 
ing system; understanding what goes on behind the scenes has a certain intrin- 
sic value. If you are interested in DOS trivia, many undocumented features of 
DOS surface in these discussions. 


DOS Data Structures 
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DOS maintains a number of data structures to track systemwide resources like 
memory and devices. These data structures are created when the kernel boots 
and are updated as the kernel processes requests. Other resources are applica- 
tion-private, but still must be managed by DOS. Let's look at these data struc- 
tures and how they are used. 


Systemwide Resources 


DOS constructs a list of device drivers, a System File Table (SFT), a Device Con- 
trol Block (DCB) list, and a Current Directory Structure (CDS). The SFT is the 
focal point for device-independent I/O. DOS uses the DCB list and CDS to help 
manage disk operations. The CDS is also where DOS stores the current default 
directory for each drive. Most DOS requests ultimately manipulate one or more 
of these data structures. 


Application-Private Resources in the PSP 
When an application starts, the DOS Kernel creates a data structure known as 


the Program Segment Prefix (PSP) which DOS uses to store application-specific 
I/O information, to process errors, and to terminate an application gracefully. 
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DOS deallocates the PSP when the application exits. Listing 10-1 illustrates the 
format of the PSP. I have arbitrarily assigned names to the various fields in this 
structure. The comments following each field describe how DOS uses that field. 
Undocumented fields are marked with an asterisk (*). 


Listing 10-1. Structure of the PSP 


PSP STRUC 
PSP_W_INT20 DW Ocd20H ; INT 20 instruction 
PSP_W_MemSiz DW 0 ; Paragraphs of memory 
PSP_B_UnusedO O08 0 ; Unknown 
PSP_T_CaLl DB 09aH,OfOH ; Far call to DOS 

DB OfeH,O1dH,OfOH ; dispatcher 
PSP_D_Term DD 0 ; Terminate Address 
PSP_D_Break DD 0 ; Break Address 
PSP_D_CritErr 0D 0 ; Critical error 
PSP_W_Parent DW 0 ; *Parent PSP* 
PSP_T_JFT DB 20 DUP COF fH) ; *JFT Table* 
PSP_W_Envron DW 0 ; Environment 

DW 0 ; Unknown 

DW 0 ; Unknown 
PSP_W_JFTSize OW 20 s *JFT Sizex 
PSP_D_JFTAddr DD 0 ; *JFT Address* 
PSP_D_Unused1 DW OffffH,OffffH 3; Unused 

DB 16 DUP CO) : Unused 
PSP_T_Parm1 DB 16 DUPCO) ; Formatted param 1 
PSP_T_Parm2 DB 20 bduP CO) ; Formatted param 2 
PSP_T_DTA DB 128 DUP(O) ; Default DTA 
PSP ENDS 


The Application Interface 


Once an application is running, it requests DOS services through the 80X86 in- 
terrupt mechanism by placing request-specific information into one or more in- 
dex registers and executing an interrupt instruction. Different interrupts 
provide a variety of services. 


The Interrupt Mechanism 


The general form of an interrupt instruction is INT nn, where nn is a number in 
the range from Oto 255. When the processor executes one of these instructions, 
the contents of the flags, code segment, and instruction pointer registers are 
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pushed on the stack. The interrupt number, nn, becomes an index into a table of 
double-word pointers in low memory called the Interrupt Vector Table (IVT). 

The IVT begins at location 0:0. Each entry contains the address of an inter- 
rupt service routine. If the processor had executed an INT 21H instruction, the 
interrupt number, 21H, would become the index into the IVT. Location 0:84H 
(84H = 4 x 21H) contains the address of the INT 21H interrupt service routine 
which will gain control as a result of an INT 21H instruction. 

Using the IVT allows DOS to dynamically alter the addresses of the intey- 
rupt service routines. This feature is important because it allows for customiza- 
tion. A number of factors, including DOS version, affect where various parts of 
the operating system get loaded. These services are requested by number and 
the kernel and the processor convert this number into an address. 

When it has completed the request, the interrupt service routine executes 
an IRET instruction which restores the processor flags and returns to the loca- 
tion following the INT instruction. 


INT 21H: The Application Workhorse 


Applications use a variety of interrupts to request kernel services, but INT 21H is 
the primary DOS interface. This interrupt provides file and device access, sup- 
ports device independent I/O, supplies status information, and controls various 
system resources. The INT 21H interrupt service routine is a significant part of 
the DOS kernel. 

An application places a value in AH to select a particular service, loads serv- 
ice-specific values into other registers, and executes an INT 21H instruction. (As 
of version 3.1 of DOS, there are 63H different INT 21H functions.) The INT 21H 
service routine contains a dispatcher which selects an appropriate internal rou- 
tine to complete the request. 


DOS-Device Driver Interface 


Just as a precise interface exists between an application and DOS, one exists be- 
tween DOS and a device driver. Each driver has a device header which helps 
DOS locate and manage the driver. 

The DOS kernel maintains a linked list of device headers. One field in this 
header contains either the address of the next header or a OffffffffH to mark the 
end of the list. The device header for the NUL device is first on this list, and the 
kernel implicitly knows the location of the NUL device header. 

Whenever DOS needs the services of a device driver, DOS constructs a re- 
quest header and calls the driver. This structure completely describes what DOS 
needs done. Listing 10-2 shows the format of a generic request header. There are 
times when the generic header cannot completely specify a request; in these 
cases, DOS appends additional fields to the request header. 
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Listing 10-2. Generic Request Header Format 


en he I I IT 


RH STRUC 

RH_B_Length DB 0 :: Length (bytes) 
RH_B_Unit DB 0 :7 Unit code 
RH_B_Command dB 0 3; Command code 
RH_W_Status DW 0 77 Operation results 
RH_T_Reserved DB 8 DUP(O) 

RH ENDS 


What Is a Driver and How Is It Used? 


DOS depends on device drivers to deal with the idiosyncracies of specific pieces 
of hardware; you can think of them as special-purpose extensions of the operat- 
ing system. Drivers isolate DOS from much of the hardware in your PC, allowing 
DOS to be ported more easily and simplifying support of new devices. 

You can find device drivers in two different places. Some drivers are actu- 
ally part of DOS and are known as built-in device drivers. Other device drivers 
exist as separate files and are called loadable device drivers. Both types of drivers 
have the same structure. 

Built-in drivers support those devices used in the boot process, which in- 
clude the console and boot disk. Locating driver code within the operating sys- 
tem simplifies the boot process. 

Loadable drivers customize and enhance DOS and are added as they are 
needed. When you configured your system, you probably decided to use 
ANSI.SYS, which modifies the way DOS deals with the console. Using a new de- 
vice is as simple as asking DOS to load another device driver. If you selected 
ANSI.SYS, you enhanced DOS. ANS1.SYS replaces the built-in console driver and 
provides added function. Loadable drivers also reduce memory requirements. 
You need only load the drivers required to support your particular hardware 
configuration. 

Each driver has three parts: a device header, a strategy routine, and an in- 
terrupt routine. The header is a data structure which the driver shares with 
DOS. The interrupt and strategy routines contain driver code and data. When- 
ever DOS needs driver service, it builds a request header, locates the driver, and 
calls the driver strategy and interrupt routines. 


The Device Header 


The header is a collection of driver specific information which DOS uses in 
much the same way as it uses the PSP for an application. In addition to the 
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address of the next header, the device header contains device attributes and the 
offsets of the strategy and interrupt routines. Listing 10-3 shows the structure of 
the device header. 


Listing 10-3. Device Header 


DHD STRUC 

DHD_A_NextDHD ODD OffffffffH 3; Address of next header 
DHD_W_Attrib OW 0 7; Device attributes 
OHD_W_StgyEntry DOW 0 53 Strategy routine offset 
DHD_W_IntrEntry DW 0 33; Interrupt routine offset 
DHD_T_Name DB 33 Device name 

DHD ENDS 


The attributes field (a two-byte word) shown in Figure 10-1 is a summary of 
device characteristics. This is an important field. It distinguishes between block 
and character devices, declares a driver's ability to handle optional requests, 
and identifies devices that require special handling. Table 10-1 lists devices and 
their functions. 
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Fig. 10-1. Driver attributes word. 


A device is either a block device or a character device. Block devices are 
usually disks and must support the MS-DOS volume structure, which absolutely 
fixes the location of certain information and establishes rules for naming and or- 
ganizing files. Character devices, on the other hand, deal with streams of bytes, 
one byte at a time. The keyboard, display, and printer are character devices. 


Strategy and Interrupt Routines 
The strategy routine records the address of the request header and returns to 


DOS. The real work of carrying out the request takes place in the interrupt rou- 
tine, which recovers the request header address and examines the request type 
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Table 10-1. Driver Attributes Field 


Device Characteristics 


CHRDEV _Set to indicate a character device. DOS treats character and block devices 
differently and uses different algorithms to locate their drivers. 

IOCTL Set to indicate driver's ability to respond to I/O Control requests. This sup- 
port is optional. These requests allow control information such as printer 
setup or communications parameters to be sent to the device. 

NONIBM _ A block device is not IBM-format compatible if this bit is set. The media byte 
takes on special meaning for IBM-format compatible volumes. If this bit is set, 
a character device can process write-until-busy requests that transfer multi- 
ple bytes with one driver request. Normally, characters are sent one at a 
time. 

OCRM If this bit is set, the driver supports open/close/removable media requests. 
Driver will be called when a file or device is opened or closed. Removable 
media requests are sent to block drivers only. 

SPECL Set to indicate that the driver has an INT 29H entry point. DOS uses this en- 
try instead of the normal request-passing mechanism to speed output to the 
current console device. (The current console device has both the STDIN and 
STDOUT bits set—see below.) This feature has been present in all recent ver- 
sions of DOS but is not documented. Use at your own risk. 

CURCLK _ Set to indicate the current clock device. DOS uses the clock device to keep 
track of the current time and date and to time-stamp files. 

CURNUL If this bit is set, the device is the current NUL device. The NUL device can be 
written to or read from. Reads always return end of file; writes always suc- 
ceed. The driver is never actually called to process these requests. 

STDIN Set to indicate that the device is the current standard input device. Certain 
characters, such as backspace, have special significance. Limited line editing 
is supported. 

STDOUT if this bit is set, the device is the current standard output device. Certain 
characters are treated specially. Nonprinting characters are converted to 
printing and tabs are expanded. 


RH_B_Command. If the interrupt routine does not support request, it returns an 
error; otherwise, it processes the request. 


Driver Dispatch 


After DOS locates the driver and constructs a request header, it places the de- 
vice header address in DS:SI, the request header address in ES:BX, and calls a 
driver dispatch routine. With the exception of initialization requests, all driver 
calls pass through this one routine. 

The dispatch routine successively calls the driver strategy and interrupt 
routines. A side effect of the dispatch logic is that the DS register contains the 
driver data segment. This feature is not documented and there is no guarantee 
that future versions of DOS will behave in the same way. Here is the code for the 
driver dispatch routine: 
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; DS:SI has device header address 

: ES : BX has request header address 

; 

CallDriver PROC NEAR 
mov ax,(si].DHD_W_StgyEntry ; ax <== strategy offset 
mov cs:temp,ax Save strategy offset 
mov cs:tempt2,ds and segment 


Indirect far call to 
strategy routine 

Now fill in interrupt 
offset 

Indirect far call to 
interrupt routine 
Return to caller 


call cs:DWORD PTR temp 


mov ax, Csi].OHD_W_IntrEntry 
mov cs:temp,ax 
call cs:DWORD PTR temp 


ret 
CallOriver ENOP 
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Using the DOS INT 21H Application Services Interface 
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We'll now examine a simple application and its interaction with DOS. The pro- 
gram, LISTER.COM, is shown in Listing 10-4. It uses INT 21H to list a file at on the 
console. LISTER opens both the file and console device, copies 256 bytes at a 
time from the file to the console, and returns to DOS after it reaches the end of 
the input file. 

Lines 1 to 4 of LISTER are typical of a COM program. COM programs al- 
ways begin execution at location 100H. Normally, this location contains a JMP in- 
struction followed by program data and then code. A COM program contains no 
address references that must be modified when the program loads. This restric- 
tion prevents COM programs from making far calls and restricts the way they 
can initialize segment registers. 

LISTER opens the input file (lines 18 to 21) and output device (lines 22 to 27) 
next. The value placed at AL prior to the open request indicates the access 
mode—0 for read-only and 1 for write. LISTER opens the input file read-only and 
the output device for write. A successful open request returns a handle in the 
AX register that DOS uses to link subsequent requests with a particular file or 
device. 

Lines 30 to 41 read 256 bytes from the input file and write them to the 
console. Notice how the read and write requests use a handle to specify the tar- 
get of the read or write operation. Each read request (Line 32) returns the num- 
ber of bytes read in the AX register. If the length of the file is not a multiple of 
256 bytes, the final read will not return the requested number of bytes. Since we 
do not want to write any more bytes than have been read, the bytes read fixes 
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the size of the next write (Line 36). If the read returns no bytes, LISTER has 
reached the end of file (ines 33 and 34) and terminates. 


Listing 10-4. 


LISTER 


Lister 


inF 
outF 
inH 
outH 
buf 
start: 


again: 


Copies program source (LISTER.ASM) to console device 


Compile: MASM LISTER; 
Link: LINK LISTER; 
Convert to COM: EXE2BIN LISTER 
EQU 100H ; € 8) 
SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME cs:_text,ds:_text; (10) 
ORG 100H 5 (11) 
PROC NEAR - (12) 
jmp start 7; (13) 
DB ‘Lister.asm’,O 3; (14) 
DB ‘con' ,0 5s (15) 
DW 0 ; (16) 
DW 0 7 17) 
DB bufS DUP(O) 7; (18) 
lea dx, inf ; 419) 
mov ax, 3d00H s (20) 
int 21H 3 (21) 
mov inH,ax 3s (22) 
lea dx ,outF s (23) 
xor CX, CX s (24) 
mov ax ,3d01H 3s (25) 
int 21H 3 (26) 
mov outH, ax : (27) 
mov cx, bufS s (28) 
lea dx, buf 3 (29) 
mov bx, inH : (30) 
mov ah,3fH 3 (31) 
int 21H 3s G2) 
or ax, ax 3; (33) 
jz done 2 (34) 
mov bx ,outH 3 (35) 
mov CX,ax 3 (36) 
mov ah, 40H 3s (37) 


LISTER.COM 


Size of program buffer 


COM programs start here 


name of input file 
name of output device 
handle for input file 
handle for output device 
read/write buffer 
address input filename 
open for read 

make request 

save handle 

address output device 
use normal attributes 
open for write 

make request 

save handle 

buffer size 

buffer address 

input handle 

read function 

make request 

end of file? 

if Z--yes 

output handle 

bytes read 

write function 


continued 


311 


Section 3: Working with the Hardware Interface 


int 21H ; (38) make request 

jmp SHORT again s (39) repeat read/write 
done: mov ah,4ch s (40) terminate function 

int 21H s (41) make request 
Lister ENDP 
_text ENDS 

END Lister 


The Boot Process 
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Now that we see what the DOS kernel can do for us, let's take a look at how some 
of this magic happens. DOS is a dynamic system, so the best way to see how its 
parts interact is to see how they are put together. The story begins when DOS 
boots. The boot process loads the operating system into memory and initializes 
the major I/O data structures. What we collectively refer to as DOS consists of 
IBMBIO.COM, IBMDOS.COM, any loadable device drivers, a command line interpreter 
or shell (normally COMMAND.COM), and possibly some Terminate and Stay Resident 
(TSR) kernel enhancer like SHARE.EXE. 

In the initial stages of the boot process, very few services are available. The 
ROM code which loads 18M810.CoM is quite primitive. IBMBIO in turn loads 
IBMDOS . COMand calls initialization code within I]BMDOS which sets up the INT 21H 
interrupt service routine. 

After this IBMDOS initialization code returns to IBMBIO, the customization 
process can begin. IBMBIO opens and reads CONFIG.SYS using INT 21H requests. 
Commands in CONFIG.SYS identify loadable drivers and override default values 
for certain DOS data structures. After CONF1G.SYS has been read, the boot pro- 
cess completes by loading the command line interpreter, COMMAND.COM. COM- 
MAND. COM initializes itself and prompts for user input. 


In the Beginning (from ROM to RAM) 


When you turn on your system or press control-alt-delete, the processor exe- 
cutes ROM code that verifies the correct operation of your system and figures 
out what equipment is present. When this Power On Self Test (POST) completes, 
it executes an INT 19H instruction to invoke the ROM bootstrap routine. 

The bootstrap routine tries to read sector 1 track 0 from drive A and then 
from the hard disk (normally drive C). This sector is the boot sector of an 
MS-DOS volume. The boot sector contains code and data needed to continue the 
boot process. Low-level, ROM-based INT 13H requests are used to read the sector. 
If neither driver responds, control passes to ROM BASIC. 

If the boot sector is successfully read, the ROM bootstrap routine jumps to 
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the entry point of the boot-sector code. This code verifies both 18MB10.ComM and 
IBMDOS.COM are present in the root directory of the boot disk, and then loads 
IBMBIO using ROM-based, INT 13H requests. 

Control passes to IBMBIO which loads 18M00s.com from disk and calls 
IBMDOS at its initialization entry point. IBMBIO passes the listhead of a linked 
list of built-in drivers to IBMDOS; the code for these drivers is part of IBMBIO. 
This list must contain headers for the disk, clock, and console devices which are 
needed to finish the boot process. It currently includes drivers for CON (the con- 
sole), AUX, PRN, CLOCK$ (the clock), COM1, LPT1, LPT2, LPT3, COM2, the 
floppy disk, and the fixed disk (if present). 


IBMDOS Initialization 


IBMDOS stores the listhead of the driver chain in the next device field of the 
NUL device header. The NUL device header, which is located in a DOS global 
table, becomes the new listhead of the driver chain. 

IBMDOS scans the driver chain looking for the console and clock devices 
and records their addresses in the DOS global table. The attributes word of the 
console driver has both the STDIN and STDOUT bits set; that of the clock driver 
has the CURCLK bit set. These devices require special treatment. 

There are times when DOS must bypass any I/O redirection. Redirection is 
a function provided by COMMAND. COMthat allows an application's input and output 
devices to be changed dynamically. DOS always checks the console device for 
control-c and reports division overflow (INT 0) to the console device. Using a 
recorded header address guarantees that these operations are not redirected. 
Simply naming a device “CON” does not make it the console device. The STDIN 
and STDOUT bits must be set in the attributes word. 

DOS uses the stored address of the clock device header to service explicit 
time or date requests and to time-stamp certain I/O operations. Recording the 
address of the clock device header is a performance optimization for time- 
stamping. The default clock device is named CLOCK$, but DOS uses the 
CURCLK bit rather than the name to find this device. 


Built-in Driver 


IBMDOS builds a request header and calls each built-in driver at its strategy and 
interrupt entry points. The driver initialization code for these built-in devices 
does very little. Character devices simply set the status word to indicate success- 
ful completion. Block device drivers also return a unit count and a table of BIOS 
parameter block addresses. Each BIOS parameter block provides basic informa- 
tion about disk structure. A block driver can support more than one device. The 
unit count tells DOS how many devices the driver actually is supporting, and 
DOS uses this information to initialize the DCB and Cache Block lists. 
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DCB 


The DCB list summarizes the disk structure information returned in the BIOS 
parameter block and records the address of the device header. The unit count 
specifies the initial size of the DCB list. Although the DCB entries for the built-in 
devices are actually contiguous, they are organized as a linked list. DOS records 
the listhead of the DCB list in the DOS global table. 

DOS needs more information about block devices than it does character 
devices. Where DOS would record the device header address for a character 
device, DOS records the DCB address for a block device. Since the DCB contains 
the address of the device header, DOS can find the header if it knows the DCB. 
Here is the structure of a device control block (none of this is documented, by 
the way): 


DCB STRUC 
DCB_B_Drive DB 0 ; [COO] Orive number 
OCB_B_Unit DB 0 ; [01] Unit number 
DCB_W_SecSize DW 0 ; (02) Sector size (Bytes) 
DCB_B_ClstMask DB 0 ; [04] Cluster size -1 

. Used as mask for finding 

H cluster boundaries 
DCB_B_ClstShift DB 0 ; (05] Sector to cluster shift 

; mask 

; Sector >> mask ==> cluster 
DCB_W_FAT1 DW 0 ; [06] LBN of 1st FAT 
DCB_B_NumFATs DB 0 ; [08] Number of FATs 
DCB_W_RootSize OW 0 ; £09] Blocks in root directory 
DCB_W_Clst2 DW 0 ; COB) LBN of first data cluster 
DCB_W_LastClst OW 0 ; [OD] Last cluster in data area 
DOCB_B_FATSize DB 0 ; COF] FAT size (blocks) 
DCB_W_RootLBN DW 0 ; (10) Root Dir LBN 
O0CB_D_Header DD 0 ; [12] Device header 
DCB_8_MediaCode DB 0 ; (16] Media code 
DCB_B_MediaChgd DB 0 ; [17] Media changed flag 
DCB_D_Next 0D 0 ; [18] Next DCB 
DCB_W_Unknown1 DW 0 ; [(1C] Unknown 
DCB_W_Unknown2 DW 0 ; [1E] Unknown 


ENDS 


Cache Block 


DOS determines the largest sector size for the built-in block devices by examin- 
ing the BIOS parameter blocks. This value fixes the size of cache blocks and con- 
sequently sets a maximum sector size for all block devices (including loadable 
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devices). IBMDOS allocates a buffer big enough to hold the largest sector and 
records its address in the DOS global table. This buffer becomes the initial disk 
cache. The INT 21H disk I/O code requires at least one cache block. DOS uses 
cache blocks to read File Allocation Table (FAT) and directory blocks and to pro- 
cess partial sector reads and writes. 

Contrary to popular opinion, the disk cache is not used to process full block 
reads and writes for ordinary files. Possibly the designers of DOS felt that it 
would be unlikely that these complete blocks would be referenced again, and so 
they would gain new! performance by not having to copy data from cache to a 
user buffer. 


The List of Lists 


DOS maintains a table of important information about the I/O subsystem. DOS 
initially records addresses for the DCB listhead, CONSOLE device header, 
CLOCK device header, and NUL device header, as well as the largest sector size 
and current number of block devices. Other information is added later in the 
boot process. 

IBMDOS passes back the address of this global table, which is sometimes 
referred to as the List of Lists, to IBMBIO. Applications can locate this structure 
through the undocumented INT 21H (AH = 52H). The following is a listing of the 
contents of this table; none of it is documented. The labels in this listing refer to 
offsets in the DOS 3.1 data segment: 


LO026 DD 0 s Listhead for Device Control 
: Blocks (DCBs) 

LOO2A DD 0 ; System File Table listhead 
s (SFT)--handles 

LOOZE DD 0 ; clock device header 

LOO32 DD 0 : console device header 

LO036 DW 0 ; largest sector 

L0038 DD 0 ; listhead for cache blocks 

LOO3C DO 0 +s address of Current Directory 
: Structure (CDS) 

LO040 DD 0 s System File Table Listhead 
>: (SFT)--FCBs 

LOO44 DW 0 ; Size of FCB SFT Table 

L0046 DB 0 s drive count 

LO047 DB 0 ; last drive 

; 

: Device header for null device 

gs 

LO048 DD 0 3 next device 

LOO4C DW 8004 * attributes 
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LOO4E DW 11418 ; strategy entry 
LO050 DW L141E ; interrupt entry 
LOO52 DB "NUL ' 3 device name 
LOOSA 0B 0 3; count of joined drives 


The IBMDOS initialization code fills in a number of entries in the IVT, in- 
cluding the address of the INT 21H interrupt service routine, and returns to 
IBMBIO, passing back the address of the List of Lists. Much of the memory occu- 
pied by this initialization code will be overwritten with DOS data later. 


DOS Returns to Its Roots 


When IBMBIO receives control again, the console, clock, and disk devices are 
initialized and INT 21His operational. IBMBIO uses INT 21H to open and read CON- 
FIG.SYS. Entries in this file customize the boot process by identifying loadable 
device drivers, controlling the size of various DOS tables, requesting specific 
processing options, and specifying a shell. 

When IBMBIO encounters a “device =” statement in CONFIG.SYS, it loads 
the driver, inserts its device header immediately after the NUL device in the de- 
vice header chain, builds an initialization request header, and calls the driver. 
The driver initialization routine performs any device-specific initialization and 
returns to IBMBIO. 

IBMBIO uses driver-supplied information from the request header to con- 
tinue the boot process. Each driver initially has all available memory allocated to 
it. The driver initialization code sets the break address in the request header 
and IBMBIO uses this information to determine where the next device will be 
loaded. 

Block drivers must also return a unit count and the address of a table of 
BIOS parameter blocks. IBMBIO adds this unit count to the current number 
block devices and uses information from the BIOS parameter block table to 
build a DCB for each unit. IBMBIO adds each new DCB to the linked list of device 
control blocks. 


Adding Some Finishing Touches 


After reading CONFIG.SYS, IBMBIO allocates the remaining cache blocks, two 
SFTs, and the CDS, and inserts their addresses in the List of Lists. Parameters in 
CONFIG.SYS may affect the size of these data structures. 
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Completing the Cache 


DOS maintains a user-selectable number of memory blocks (a cache) for buffer- 
ing disk I/O operations. Either a “buffers =” statement in CONFIG.SYSor a default 
value sets the number of cache blocks. IBMBIO allocates the remaining cache 
blocks and inserts them in a linked list of available blocks. 

There are 16 bytes of overhead for each cache block. DOS uses this space to 
manage the disk block cache. The next listing illustrates the layout of a cache 
block. Note that the largest sector on a built-in block device sets the size of the 
data area. This listing assumes the normal value of 512 bytes. This information is 
also undocumented. 


STRUC ccB 

CCB_D_NextCCB ODD 0 ; COOH) Next CCB in Linked list 
CCB_B_Owner DB 0 ; CO4H] Owning Drive 
CCB_B_Status DB 0 ; COS5H] Status of block 
CCB_M_IsFAT EQU 02H 3; This block is a FAT 
CCB_M_IsDir EQU O4H ; This is a directory Block 
CCB_M_IsData EQU O8H ; This is a data block 
CCB_M_IsValid EQU 20H ; This block is valid 
CCB_M_IsDirty  EQU 40H ; This block is dirty 
CCB_W_LBN DW 0 ; CO6H) Block number 
CCB_W_Count DW 0 ; CO8H] Number of blocks 
CCB_D_DCB DD 0 ; (OaH] DCB of owning drive 
CCB_W_Flags DW 0 ; [(OeH) Flags 

CCB_T_Data DB 512 DUP(O) ; C10H] Data from disk 
cCcB ENDS 


The System File Table 


The SFT is one of the principal MS-DOS I/O data structures and is the focal point 
for device independent I/O. Whenever DOS initially accesses a file or device, it 
creates an SFT entry. This entry records the file/device name, directory attri- 
butes, device attributes, context information such as file size and position, and 
either the DCB (block devices) or Device Header (character devices) address. 
DOS uses separate SFTs for File Control Block (FCB) and handles. FCBs are an- 
other technique for accessing files and devices, providing the same basic capa- 
bilities as handles. 

The size of the FCB System File Table is fixed by an “fcb =” statement in 
CONFIG.SYSor a default value. The handle table can grow dynamically. Here is the 
format for an SFT entry. This information is undocumented. 
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SFT STRUC 

SFT_W_RefCnt DW 0 ; (00) reference count 
SFT_W_Mode DW 0 ; [02] open mode 
SFT_M_FCB EQU 8000H ; Entry is for FCB 


SFT_M_DenyNone EQU Q040H =; Sharing bits (4-6) 
SFT_M_DenyRead EQU COSOH =; ” 
SFT_M_DenyWrite EQU QO20H_ ; " 
SFT_M_Exclusive EQU O010H ; “ 


SFT_M_NetFCB EQu OO70H ; This is a network FCB 
SFT_M_Write EQu COO1H ; File access bits (0-2) 
SFT_M_Read EQU COCOH |; ue 
SFT_B_DirAttrib DB 0 ; [04] 

SFT_W_Flags DW 0 ; (O05) 


Network access 

Date set (FILE only) 

IOCTL support (DEVICE only) 
Entry is for a device 
(DEVICE) end of file on input 
(DEVICE) transparent mode 
(DEVICE) supports INT 29H 
(DEVICE) current clock device 
(DEVICE) current nul device 
(DEVICE) current stdout device 
(DEVICE) current stdin device 
(FILE) file written 

(FILE) mask for drive bits 


SFT_M_Shared EQU 8000H 
SFT_M_DateSet EQU 4000H 
SFT_M_IOCTL EQU 4000H 
SFT_M_IsDevice EQU OO80H 
SFT_M_EOF EQU 0040H 
SFT_M_Binary  EQU 0020H 
SFT_M_Special EQU 0010H 
SFT_M_IsClock EQU 0008H 
SFT_M_IsNul EQU O004H 
SFT_M_IsStdOut EQU 0002H 
SFT_M_IsStdIn EQU 0001H 
SFT_M_Written EQU 0040H 
SFT_M_DriveMask EQU 003 FH 


=e =e me 


=e “8 %6¢ Se Se We Be =e 6&8) 6&e 


: (0-5) 
SFT_D_DCB DD 0 ; [O07] CFILE) DCB address 

. (DEVICE) Header address 
SFT_W_Cluster1 DW 0 ; (OB) (FILE) initial cluster 
SFT_W_HHMMS DW 0 ; [OD] (FILE) Hour, Min, Sec/2 

. Access time 
SFT_W_YYMMDD DW 0 ; COF] (FILE) Year, Month, Day 

: Access date 
SFT_D_FilSiz DD 0 ; (11] File size / EOF location 
SFT_D_FilPos DD 0 ; £15] Current file position 
SFT_W_RelClstr OW 0 ; [19] CFILE) clusters from 

: beginning of file 
SFT_W_CurClstr OW 0 ; (1B) (FILE) current cluster 
SFT_W_LBN DW 0 ; [1D] CFILE) block number 
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SFT_W_DirIndex DB 0 ; (1F] (FILE) directory index 
SFT_T_FileName D8 OBH DUPCO) ; [20] (FILE) file name 
SFT_T_Unknown DB O4H DUP(O) ; (28) 7777 
SFT_W_OwnerMach DW 0 {[2F] Machine number of file 


owner 


we se =e =e 


SFT_W_OwnerPSP DW 0 [31] PSP of task that 
initially accessed file 
? accessed file 
SFT_W_Status DW 0 ; (33] Status 
ENDS 
Building the CDS 


The LASTORIVE statement in CONFIG.SYS or a DOS default value fixes the size of 
the CDS. There is one CDS entry for each possible drive and all entries are con- 
tiguous so the drive number can be used as an index. DOS uses the CDS to pro- 
cess joined, substituted, and network drives, and to maintain current directory 
information. 

Each CDS entry has a device name, current default directory, DCB address, 
and flags field. The 43H bytes of device and directory information include a 
drive letter, a colon (:), a backslash (\), and a null to terminate the string. The 
path-and filename can be up to 64 (40H) bytes long. The size of the name field is 
what limits the length of a filename. The flags field identifies joined, substituted, 
and network devices. The search for a block driver begins by using the drive 
number as an index into the CDS. 

Here is the format of the CDS. None of the information in this listing is docu- 
mented. 


CDS STRUC 

CDS_T_Name DB 43H DUP(O) ; [00] Device and directory 
; name 

COS_W_Status DW 0 ; (43] Device status 


CDS_M_Network EQU 8000H 
CDS_M_Local EQU 4000H 
CDS_M_Joined EQU 2000H 
COS_M_Substitue EQU 1000H 
COS_M_Device EQU 0080H 


Network device 
Local device 
Joined device 
Substituted device 
Device 


m6 me ae 


=e 


CDS_D_0CB DD 0) ; [45] Address of DCB 
CDS_T_Unknown DB 8 DUP(O) ; [49] Unknown 
ENDS 
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DOS at Your Command 


At this point IBMBIO has completed all the major DOS I/O data structures. Figure 
10-2 illustrates the relationships among these structures. IBMBIO runs the com- 
mand-line interpreter (shell). The default shell is COMMAND.COM, but a COMSPEC = 
statement in CONFIG.SYS can select an alternate shell. 


FCB Handle 
SFT SFT 


Clock 
Console 


A\FOO 


of 


tN 
C:\BAR 
DAJUNK 
Cache 
Blocks 


Header Device Current 
Chain Control Directory 
Blocks Structure 


Fig. 10-2. DOS I/O data structures. 


The boot process ends when the shell is run. The shell relies on DOS serv- 
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ices to do its job, using INT 21H to display the shell prompt A>, read from the 
keyboard, and invoke other applications. 


The INT 21H Dispatcher: Processing Application 
Requests 


Now that the boot process is finished, DOS stands ready to process application 
requests, many of which come through INT 21H. The first part of the INT 21H in- 
terrupt service routine is a service dispatcher that stores values in static vari- 
ables, changes to one of three different stacks, and calls a routine to perform the 
requested function. 

Before returning to its caller, the INT 21H dispatcher must restore the static 
information and stack. If the INT 21H dispatcher is reentered before it can restore 
this information, DOS may become confused and go off the deep end. 

If either a driver or a background process issues an INT 21H request, it can 
cause the INT 21Hdispatcher to be reentered. The architecture of this dispatcher 
restricts background processing and limits what a driver can do. It is important 
to understand what happens in this section of code. 


Initial Processing 


The request type passed in AH is validated. Four requests are serviced immedi- 
ately—get PSP (AH = 50H and AH = 62H), set PSP (AH = 51H), and get/set/ 
check break state (AH = 33H). The requests corresponding to AH = 50H and 
AH = 51H are undocumented. These immediately completed requests are al- 
ways safe to make. We probably would never have occasion to use any of these 
requests from a driver but they are necessary for background programs. 

If the request cannot be immediately satisfied, DOS saves all registers on 
the current stack and also records contents of the current DS:BX register pair in 
a static variable (many INT 21H requests pass an address in DS:BX). 


INDOS Flag 


Most of the remaining code is a critical section which must be completed with- 
out interruption. The INT 21H dispatcher increments the infamous INDOS flag 
when it begins this critical section and decrements the flag at the end. 

The purpose of the INDOS flag is support of background programs like 
PRINT.COM. Background programs initially run from the DOS command prompt, 
and after performing any initialization, they terminate and stay resident. (See 
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Essay 7, Safe Memory-Resident Programming (TSR), by Steven Baker, for a thor- 
ough discussion of these programs.) Their initialization should record the ad- 
dress of the INDOS flag. The undocumented INT 21H AH = 34H returns the 
address of this flag in the ES:BX registers. Note that this request can only be 
safely made when the TSR initializes. 

A zero value of the INDOS flag is not an absolute guarantee that it is safe to 
make an INT 21Hrequest. When DOS processes a critical error, it decrements the 
INDOS flag and increments a critical error flag. A critical error is an I/O error 
which cannot be handled by the device driver. The location of the critical error 
flag varies with DOS version, and both critical error and INDOS flag must be 
checked. In DOS 3.1, the critical error flag is the byte before the INDOS flag. 


Dispatcher Stack Switching 


The INT 21H dispatcher works with three separate stacks: user, auxiliary, and 
disk, and switches among these stacks depending on the request and critical 
error flag. 

The current SS:SP register values are saved in a static variable after saving 
the previous variable contents in another static variable. This action provides 
one level of INT 21H recursion needed to support background processing. 5S:SP 
values are also recorded in the PSP of the current task, and are used to restore 
the stack when the current process terminates. 

The current stack is unconditionally changed to the auxiliary stack. If the 
request is for termination (AH = 0) or get extended error (AH = 59H), it is serv- 
iced directly. If the request is in the range 01H to OCH and a critical error is not in 
progress, a change is made to the user I/O stack. Critical Error Handlers can 
safely make INT 21H requests in the range 01H to OCH because no stack switch is 
performed. For all other requests, the disk stack is used. 


Taking a Break 


If the break flag has been set either by a break = onstatement in CONFIG.SYSor by 
an explicit INT 21Hrequest (AH = 33H) and the disk stack is in use, a nondestruc- 
tive read is issued directly to the console driver to check for control-c. Some of 
the user-stack requests make an unconditional control-c. 

Since control-c checks are sent to the console device, DOS uses the header 
address from the List of Lists to locate its driver. If a control-c is detected, the 
DOS kernel executes an INT 23H. COMMAND.COM sets up an INT 23H service routine 
which terminates the current program, but a program can override this action 
by declaring its own INT 23H service routine. Because of the way the INT 21H dis- 
patcher switches stacks, it is not safe to issue an INT 21Hrequest from an INT 23H 
interrupt service routine. 
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Finishing the Job 


For all unsatisfied requests, the dispatcher uses the function code (initial AH 
value) as an index into a table of internal service routines. In recent versions of 
DOS, this table begins at offset OdefH of the DOS segment. 

When the internal DOS routine returns, the INT 21H dispatcher decrements 
the INDOS flag, restores the caller's stack pointer, removes the saved registers 
from the caller’s stack, and executes an IRET instruction. 


Using FCBs and Handles 


The majority of the INT 21H requests are I/O related. There are two basic tech- 
niques for requesting a DOS I/O operation: handles and FCBs. 

Handles were introduced with version 2.0 of DOS, and they support the 
hierarchical file system (i.e., directories and subdirectories). Initial access to 
files and devices is by name, which can include a path. A path contains drive and 
subdirectory names in addition to the file or device name. Open or create func- 
tions return a number called the handle which is used in place of the name for 
subsequent accesses. When you use handles for read or write, you specify the 
number of bytes that you want to transfer, a buffer address, and the previously 
returned handle. 

FCBs are an artifact of version 1.0 of DOS and do not support the hierarchi- 
cal file system. You create the FCB data structure and pass it to the INT 21H dis- 
patcher with each request. Transfers are measured in records instead of bytes; 
each FCB has its own record size. The Disk Transfer Area (DTA) is a common 
buffer for all transfers. Here is the format of an FCB (items marked with an aster- 
isk are undocumented FCB fields): 


; FCB.DEF 

, 

FCB STRUC 

FCB_B_Drive DB 0 ; (00) Orive number 
FCB_T_Name DB : ' ; [01] Name 

FCB_T_Ext DB : j ; [09] Extension 

FCB_W_CB DW 0 ; (12) Current block 
FCB_W_LRS DW 0 ; (14] Logical Rec Size 
FCB_D_FS DD 0 ; (16) File Size (bytes) 
FCB_W_DLM DW 0 ; [20] Date Last Modified 
FCB_W_TLM DW 0 ; [22] *Time Last modified 
FCB_B_SFN DB 0 ; [24] *SEN 

FCB_B_Flags DB 0 s (25] Modified flags 
FCB_A_DHD DO 0 ; [26] *Device Header/DCB 
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DW 0 ; (30) 
FCB_B_BRR DB 0 : [32] Block Relative Rec 
FCB_D_FRR DD 0 ; (33] File Relative Rec 
FCB ENDS 
Working with the SFT 
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Handles and FCBs are application data structures, but, internally, DOS deals with 
SFT entries, maintaining separate SFTs for handles and FCBs. The entries in 
each table are assigned a number which ranges from zero to the number of ta- 
ble entries minus one. DOS allocates an SFT entry when the file or device is ini- 
tially accessed. The number assigned to this entry becomes the System File 
Number (SFN) and links FCBs and handles to their corresponding SFT entry. 


Handles 


The handle returned by an open or create is an index into a data structure called 
the Job File Table (JFT). A handle of 0 references the first element of this table, 1 
the second element, etc. The contents of each element of the JFT is the SFN, 
which is used as an index into the handle SFT. 

DOS records the address and size of the JFT in the Program Segment Prefix 
(PSP) because the JFT and associated handles are application-private resources. 
The JFT normally holds 20 entries (i.e., there are 20 handles) and can usually be 
found within the PSP. The size of the JFT sets a limit on the number of open files. 

There is not room within the PSP to expand the size of the JFT, but you can 
allocate a new JFT and update the size and base address in the PSP. DOS never 
assumes that the JFT is located in the PSP. The capability to grow the JFT this 
way has existed for some time, but it has not been documented. DOS 3.3 pro- 
vides an INT 21H function to increase the size of the JFT. 

After the initial file or device access, DOS uses the handle as an index into 
the JFT where it finds the SFN and uses it to find the original SFT entry. Figure 
10-3 illustrates the relationship between the handle, PSP, JFT, SFN, and SFT. 


FCBs 


There is no central structure analogous to the the JFT for File Control Blocks. 
DOS records the SFN assigned at the initial access in one of the reserved fields of 
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Address of next SFT group ee of 
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Fig. 10-3. Program I/O data structures. 


the FCB, which is passed back to DOS in subsequent I/O operations. DOS ex- 
tracts the SFN and locates the corresponding entry in the FCB SFT. 


From Driver Request to Call 


Now that we have surveyed the general structures involved with file I/O, let’s ex- 
plore the transformation of some of the more common INT 21H requests into 
driver calls. Operations such as open, close, read, and write originate as either 
handle or FCB requests, which DOS converts to a standard format before calling 
a common internal routine to complete the request. This internal routine uses 
information in an SFT entry to build a request header and locate the device 
driver. Various important pieces of information are stored in static DOS variables 
contributing to DOS reentry problems. 

Understanding the mechanics of this process is helpful for writing drivers. 
You will know the types of requests DOS will send to your driver and the circum- 
stances under which they will be sent. It is not exactly obvious when a driver 
will receive flush, status, and nondestructive read requests. Device attributes 
have some interesting side effects on the transformation process. 

I'll explain how DOS uses the different I/O data structures to locate the 
driver and complete the request. Familiarity with these structures is an asset for 
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debugging. The information which they contain tells you where DOS loaded 
your driver, how many characters your driver has processed, and what DOS 
knows about your driver. 


Opening a Device 


Either a handle or an FCB request can open a device. The separate routines for 
these requests eventually call a common internal open routine to complete the 
operation. The different entry points map handle and FCB requests into the SFT 
entry needed by the internal open routine. 

DOS always assumes a file to be the target of all open requests and concate- 
nates a drive name and directory string with the device name to complete a 
pathname. If this information is not explicitly contained in the initial reference, 
the current default drive and directory for that drive are used. The internal 
open routine parses this pathname and eventually discovers device references. 
This logic may seem warped, but it has the advantage that files and devices can 
be treated uniformly. On some systems, the semantics of device names (always 
ending in a colon or beginning \dev\foo when foo is the name of a device) allow 
the operating system to recognize a device reference. DOS cannot immediately 
determine whether a name refers to a file or a device. 

Handle and FCB open requests pass through the INT 21H function dis- 
patcher to separate routines that call a common internal open routine. It is this 
internal open routine which does most of the actual work needed to open a de- 
vice or file. 

A successful open request allocates an SFT entry containing the address of 
the device header if a device is being referenced, or the address of a DCB contain- 
ing the address of a device header if a file is being referenced. The SFN identifying 
the SFT entry is stored in the JFT for handle operations and in the FCB for FCB 
operations, and will direct subsequent accesses quickly to the correct SFT entry. 


Handle Open 


The handle open routine allocates an SFT entry from the handle SFT and a han- 
dle from the JFT. The SFN corresponding to the newly allocated SFT entry is 
recorded in the JFT. 

If the input file/device name does not contain an explicit device or begin 
with quotation marks, the current default drive and CDS are used to construct a 
complete pathname. The flags and status fields in the SFT entry are initialized 
and the internal open routine is called. 

The handle open routine sets the reference count in the SFT entry to 1 if 
the internal open routine completes successfully; otherwise, it must deallocate 
the SFT entry and handle and return an error code. 
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FCB Open 


The FCB open routine sets the file open attributes to read/write for compatibil- 
ity with the handle open. The FCB open routine creates a pathname by concate- 
nating the current default drive and directory from the CDS with the name in 
the FCB. An SFT entry is allocated from the FCB SFT and the SFT flags field is set 
to indicate FCB access. A call is made to the internal open routine. If this routine 
returns successfully, the SFT reference count is incremented, some FCB fields 
are initialized, and information is copied from the SFT entry back to the FCB. 

Whenever an open request is made, a new FCB SFT entry is allocated. Be- 
cause of the way file sharing is implemented for FCB access, an SFT entry corres- 
ponding to the same file may have been previously allocated. The FCB open 
routine scans the SFT after each request looking for duplicate entries. If there is 
another SFT entry that references the same file, the reference count and “age” 
are updated and the new SFT is deallocated. FCB SFT entries are aged, and if an 
SFT entry is needed and none are available, the oldest one is reused. Sufficient 
context information is maintained in the FCB to reconstruct the SFT entry at a 
later time. 


The Internal Open Routine 


DOS calls a common internal open routine to process both handle and FCB re- 
quests. This routine validates the open attributes and examines the SFT flags. 
Requests for access to a network device are immediately passed to MSNet using 
INT 2FH; otherwise, a device/file lookup is performed. 

The lookup operation is complex and is mainly of interest for processing 
block device requests. The pathname (drive letter + directory string + file/ 
device name) is scanned from left to right looking for tokens (a string of charac- 
ters separated by directory delimiters \ or ending with a nul \000). The list of 
device headers is scanned in an attempt to match the name of a character driver 
with the token. If the last token from the path (i.e., it ends with a nul) matches 
the name of a character device, the DOS kernel concludes that this device is the 
target of the open request. 

If a character device is not being referenced, the token must refer to a di- 
rectory entry. DOS reads directory blocks from disk until it locates the directory 
corresponding to the token. These steps are repeated for each token until the 
directory search fails or the end of the path is reached. 

Since the header chain is searched starting from the NUL device and work- 
ing backward, the last device loaded with a particular name is the first one 
found. Any character device except the NUL device can be replaced by loading a 
similarly named device driver. 

If the open request completes successfully and the device supports open/ 
close/removable media functions, DOS sends an open request to the appropriate 
device driver. The driver indicates support for these functions by setting the 
OCRM bit in the device header. Control returns to the handle or FCB open routine. 
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Reading and Writing 


Both handles and FCBs can be used to request read or write operations. Each 
access method follows a different path through the INT 21H dispatcher, but even- 
tually arrives at common internal read and write routines. The internal routines 
actually perform the I/O operation using information contained in SFT entries. 
The various routines along the separate code paths hide the differences be- 
tween FCB and handle access from the internal I/O routines. 


Handle Access 


The INT 21H dispatcher calls separate entry points to process read and write re- 
quests. This code quickly merges to a common read/write routine. 

The read/write routine uses the handle to locate the SFT entry and checks 
handle ownership by comparing the current PSP to the value recorded in the 
owner field of the SFT entry. The buffer address is adjusted to minimize “seg- 
ment wrap” (i.e., the offset is made as small as possible and either the internal 
read or internal write routine is called to complete the transfer). 


FCB Access 


There are specific FCB requests for reading and writing records sequentially 
and randomly. Sequential operations deal with a single record at a time, and ran- 
dom operations can process multiple records. There are different INT 21H re- 
quests for each case. These separate routines call a common FCB I/O routine 
which converts the request size to bytes and the record-oriented FCB position to 
a byte-oriented file position. Next, the transfer size is adjusted to prevent seg- 
ment wrap and an SFT element is allocated. Context information is moved from 
the FCB into this newly initialized SFT element. 

Control now passes to the same internal read and write routines used to 
satisfy handle requests. After the internal routine completes, the file size is cop- 
ied back to the FCB and the number of records processed is calculated. This 
number will differ from the requested number if the transfer size was altered. 

If a read resulted in transfer of a partial record, DOS zeros the unused part 
of the buffer. All FCB operations implicitly use the DTA as a buffer. If a write 
operation is completed, the common FCB I/O routine calls an interna! routine to 
get the current date and time. The time and date routine creates a request 
header and passes it to the current clock device using the previously recorded 
device header address. The FCB relative record field is updated regardless of the 
operation performed. The number of records written and final status are re- 
turned. 
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Internal Read Routine 


The internal read routine verifies that read access to the device is allowed (a 
device such as a printer might be write-only), sets the error locus (for extended 
error processing) to serial device, and examines the device attributes in the flags 
word of the SFT entry. Some of these attributes were copied from the device 
header when the SFT entry was created, and others updated as the device is 
used. If an end of file has been detected or the device is the current NUL device, 
the read terminates immediately. 

If the flags field indicates that device is in binary or raw mode (set by an 
Input/Output Control (OCTL) request), a single read request is sent to the device 
driver. Binary mode processing can offer a substantial performance advantage, 
but the request will not terminate until the specified number of characters have 
been read. 

There are two execution paths for text I/O because reads from standard 
input require special handling. If the device is not standard input, the kernel 
builds a one-character read request header, makes a control-c check, and calls 
the driver. If the read request is successful, this routine updates the buffer ad- 
dress and checks for end-of-file (EOF) or carriage routine. If either of these char- 
acters is found, the read terminates; otherwise, the steps are repeated until the 
requested number of characters have been read. 

If the device is standard input, the internal read saves the address of the 
SFT entry in another DOS global variable and converts the request to a buffered 
read from standard input corresponding to INT 21H (AH = OAH). The buffered 
read routine takes care of echo and special character processing and supports 
limited editing. 

The internal read routine updates the SFT entry after the read request 
completes. It calculates the bytes read and updates the total number of bytes 
processed since the device was opened. This count, analagous to file position for 
file operations, is stored in the file position field of the SFT. If an end of file was 
detected, the SFT flags field is set accordingly. The internal read routine checks 
the status returned by the device driver in the request header and invokes the 
DOS Critical Error Handler to deal with any errors. 


Internal Write Routine 


The internal write routine verifies that write access is permitted, sets the error 
locus to serial device, and sets the not-at-end-of-file bit in the SFT entry flags 
field. The internal write routine checks the current mode and device attributes 
in the SFT entry flags field. 

If a device is being accessed transparently, a single write request is passed 
to the appropriate driver. Since individual characters are not checked in trans- 
parent mode, there is no notion of end of file. This mode is useful for sending 
certain bit-mapped graphics to a printer. The bit pattern corresponding to EOF 
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cannot be sent to a device in text mode. There are also performance advantages 
with transparent mode since the driver is called only once for each request. 

There are two special cases for text mode I/O. If the device is the current 
NUL device, DOS declares the operation successful and returns without ever 
calling the driver. Writes to standard output are passed to the DOS display out- 
put routine (the same one used to process INT 21H, (AH = 02H) requests) which 
is described later on. 

Text mode I/O of any other device is processed one character at a time. DOS 
builds a request header for a single character write, makes a control-c check, 
and passes the request to the driver. If the driver does not return an error, the 
buffer address and character count are updated. This process continues until 
either an end of file is written or all the characters have been processed. 

The Critical Error Handler processes any errors and may terminate the 
current process. After the write completes, the internal write routine updates 
the SFT entry and returns to its caller. The number of bytes written is calculated 
by subtracting the initial buffer address from the current buffer address. This 
value will eventually be returned to the application through the INT 21H function 
dispatcher. The file position is updated by adding the number of bytes written to 
the old position. (For a device, the file position is the total bytes written since the 
device was opened.) 


Closing a Device 


Closing a device releases the resources which DOS allocated when it opened the 
device. Handle and FCB close requests eventually call a common internal close 
routine. 

The handle close routine is called directly from the INT 21H function dis- 
patcher. It validates handle ownership by comparing the current PSP to the own- 
ing PSP stored in the SFT entry; only the handle owner can close a file. If the 
reference count is 1 or the SFT entry does not correspond to a network FCB, the 
corresponding SFN is extracted from the Job File Table, and the handle is 
marked as available. In either case, control] passes to the internal close routine. 

The FCB close routine retrieves the SFN from the FCB and copies the cre- 
ation data and time from the FCB to the SFT entry. The flags field of the SFT 
entry is updated to indicate that the file date has not been set. The date and time 
will be needed to update directory entries for modified disk files. The internal 
close routine will complete the FCB close request. 

Closing local devices is a simple operation. The reference count in the SFT 
entry is decreased and when the count becomes zero, the entry is released. If 
the device supports open/close/removable media requests and the current PSP 
owns the SFT entry, a close request is sent to the device driver. This ownership 
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requirement can prevent a driver from receiving a close request even if the 
OCRM bit is set in its header. COMMAND. COMopens PRN, CON, and AUX. Any appli- 
cation run by COMMAND.COM gets access to these devices without opening them 
through a mechanism known as inheritance. Since COMMAND.COM and not the ap- 
plications owns these devices, the driver will not be called when an application 
closes them. The Critical Error Handler is called if the driver reports an error. 


IOCTL Requests 


IOCTL requests provide some control over DOS/driver interactions. For exam- 
ple, they can return device attribute information or change between binary and 
text mode. We've seen that mode can affect the transformation of read and write 
requests. 

Applications initiate IOCTL requests with an INT 21H request (AH = 44H); 
the AL register selects an IOCTL subfunction. Some IOCTL requests are sent 
only to block devices and are not discussed in this section. 

The DOS kernel can satisfy some requests without calling a driver, but it 
must send either a status or an IOCTL request to complete others. A driver re- 
ceives the IOCTL request only if the IOCTL bit is set in its header. 

Since the DOS kernel needs information from the SFT to satisfy device 
IOCTL requests, a handle must be passed in the BX register. Applications must 
either explicitly open a device or reference one that is permanently open such as 
StdIn or StdOut. DOS validates the handle and then dispatches on the subfunc- 
tion contained in AL. 


Get and Set Device Information 


Recall that the Stdin, Stdout, and Binary attributes directly affect request trans- 
formation. Applications use IOCTL requests to change these attributes. DOS re- 
cords device attribute information in the SFT and uses that entry to satisfy these 
requests. It will process Get or Set Device Attributes (AL = 0 and AL = 1) re- 
quests whether or not a driver provides IOCTL support. A driver cannot prevent 
an application from selecting binary mode and must be prepared to deal with 
multiple byte reads and writes. 

The program in Listing 10-5, BINMODE, illustrates the use of Get and Set 
Attributes IOCTL requests. Lines 13-15 make an IOCTL Get Attributes request 
for the current standard output device. The handle for StdOut is permanently 
assigned, and we do open it explicitly. At line 16, we examine the returned attri- 
butes. If StdOut is a device, we issue a set device attributes IOCTL request in 
lines 18-21. 
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Listing 10-5. 


ee ee ed | 


=e =e =e 


_text 


BinMode 


notdev: 


BinMode 
_text 


Use the procedure described in the listing comments to create BINMODE. COM; 
you can use DEBUG to demonstrate the effect of this program. I You must be very 
careful with DEBUG. DEBUG is cryptic and unforgiving; it can easily trash your hard 
disk. Make sure that you enter the program and DEBUG commands exactly as listed. 

DEBUG prompts for input with - and occasionally with :. You must enter the 
responses in italics. Note that you may see different values in your segment regis- 
ters. At 1544:0117, tabs are no longer expanded; your console (the default StdOut 


BINMODE 


BINMODE.ASM 
IOCTL demonstration program 


Create this program in a file called BINMODE.ASM 
Assemble: MASM BINMODE; , 

Link: LINK BINMODE; 

Make COM file: EXE2BIN BINMODE BINMODE.COM 


SEGMENT BYTE PUBLIC ‘CODE’ 

ASSUME cs:_text,ds:_text 

ORG 100H 

PROC NEAR 

mov bx,1 3; [13] bx <== stdout handle 

mov ax, 4400H ; [14] ax <== IOCTL get attributes 
int 21H : [(15] make the request 

test di ,80H ; (16) is it a device? 

jz notdev ; (171 if Z--no 

or dt,20H ; €18] put device in binary mode 
xor dh,dh : (19) dh <== 0 (required) 

mov ax, 4401H s [20] ax <== IOCTL set attributes 
int 21H : [21] make the request 

mov ah,4cH ; [C22] return to DOS 

int 21H 

ENDP 

ENDS 

END BinMode 


device) is in binary mode. 


A>DEBUG BINMODE.COM 


-9115 


AX=4401 
DS=1544 


1544:0115 CD21 


BX=0001 Cx=001B DX=00F3 SP=FFFE BP=0000 SI=0000 DI=0000 
ES=1544 S$S=1544 CS=1544 IP=0115 NV UP EI PL ZR NA PE NC 
INT 21 
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-9117 


AX=44D3 BX=0001 CX=001B DX=00F3 SP=FFFE BP=0000 $1=0000 01=0000 
DS=1544 ES=1544 SS=1544 CS=1544 IP=0117 NV UP EI PL ZR NA PE NC 
1544:0117 B44C MOVOAH,4C 


“9 
Program terminated normally 
-q 
A> 


The console is now in binary mode; you probably don’t want to leave it in 
this condition. You can either reboot your system or restore it with this pro- 


gram. The following DE8UG session will restore your console to text mode. 


A>DEBUG BINMODE.COM 
~9115 


AX=4401 Bx=0001 Cx=001B DX=00F3 SP=FFFE BP=0000 S1=0000 DI=0000 
DS=1544 ES=1544 $S=1544 CS=1544 IP=0115 NV UP EI PL ZR NA PE NC 
1544:0115 CD21 INTo21 

-rdx 

DX OOF3 

203 

-9117 


AX=44D3 Bx=0001 CX=001B Dx=00D3 SP=FFFE BP=0000 SI=0000 D1I=0000 
DS=1544 ES=1544 SS=1544 CS=1544 IP=0117 NV UP EI PL ZR NA PE NC 


1544:0117 B44C MOV AH,4C 
“g 

Program terminated normally 

—q 

A> 


At 1544:0115, tabs are not yet expanded; the console is still in binary mode. 
Altering the value in DX (the rdx command) causes the INT 21H instruction to 
restore the console to text mode. Notice how tabs are expanded at 1544:0117. 


Read and Write Control Information 


Read and Write Control Information (AL = 2and AL = 3)IOCTL requests allow 
applications to exchange arbitrary control information with a driver. An applica- 
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tion might send an IOCTL request whichs sets transmission speed or parity to a 
communications driver. Programs can send these requests to the SOUND driver 
to contro] various music synthesis parameters and retrieve error information. 
(See Essay 11, Writing a SOUND Device Driver.) DOS will not send these requests 
to a driver unless the IOCTL bit in the device header attributes word is set. 


Get Input and Output Status 


IOCTL requests also can cause DOS to send Input and Output Status (AL = 6 
and AL = 7) requests to a device driver. Currently, IOCTL requests are the only 
way to generate an output status request header. The DOS kernel routes these 
status requests to the driver regardless of the setting of the IOCTL bit in the 
device header. 


Character I/O Routines 


The INT 21H interface provides a group of Character I/O (AH = 01H to OCH) rou- 
tines which are important because they provide hooks for background process- 
ing and frequently can be called from a device driver. These routines support 
input editing and output logging. Output logging creates a listing of console out- 
put on your printer. The internal read and write routines rely on these functions 
to handle text mode I/O to the standard input and output devices. 

Each routine in this group implicitly uses one of the permanently assigned 
handles (standard input = 0, standard output = 1, standard error = 2, stan- 
dard auxiliary device = 3, and standard printer = 4) and always verifies the 
handle before proceeding. Because StdIn amd StdOut can be redirected, any 
driver should be prepared to receive these requests. 

These routines are the source of buffer flush and input status requests. Al- 
most all of the input routines in this group send read/nowait requests to the driver 
directly or indirectly. A number of these routines call a keyboard poll or back- 
ground processing routine which are DOS's hooks for background processing. 


Display Output 


The Display Output (AH = 02H) service writes a single character to the current 
standard output device; it is also called indirectly by the internal write routine as 
a result of a text mode write to standard output. 

Display Output converts control characters to sequences of printable char- 
acters and maintains a current display column. For each printable character, an 
internal write character routine is called. This routine examines the IsSpecl bit 
in the device header. If this bit is set, the character is passed to the device driver 
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via the undocumented INT 29H interface instead of using a request header. The 
INT 29H interface speeds up the process of passing a character to the driver. The 
write routine places the character in DL and executes INT 29H. 

After every fourth character is written, the Display Output routine calls 
the keyboard poll routine; it also supports screen logging. Each time a character 
is written, this routine checks the screen logging state. If logging is active and 
the handle for the standard print device (handle = 4) is valid, the character is 
written to the printer as well as StdOut. 


Buffered Keyboard Input 


Buffered Keyboard Input (AH = OAH) reads one line from the current standard 
input device and supports limited line editing. This routine can also be called 
indirectly by the internal read routine as the result of a text mode read from 
standard input. The line-editing capability is an internal DOS function not asso- 
ciated with a particular device. So long as standard input is a device, DOS will 
provide editing capability. 

Internally, the buffered keyboard input routine calls the console input 
without echo (INT 21HAH = 8) which repeatedly calls the keyboard poll routine 
until a character is available. A single character read request is sent to the StdIn 
device driver. 


Keyboard Poll Routine 


Several of the character I/O routines call the keyboard poll routine to check for 
control-c, control-s, and control-p characters. The control-c check is done first. 
Since a control-c has special significance only if entered from the keyboard, the 
address of the console device recorded in the boot sequence is used to locate the 
driver. Control-c checks cannot be redirected. A read/nowait request is sent to 
the initial console device. If the device returns a control-c in the read/nowait 
request header, DOS issues an INT 23H. Programs can set up their own INT 23 
service routines to trap control-c. By default, the DOS kernel calls the com- 
MAND.COM INT 23H service routine which terminates the current program. 

If no control-c is found, a read/nowait request is sent to the current stan- 
dard input device. If the device is busy, the background processing dispatcher is 
called and the keyboard poll routine exits. If the read/nowait detects a control-s 
(suspend output), a background processing loop is entered. This loop repeatedly 
checks the keyboard and calls the background processing dispatcher until key- 
board input is detected. If the read/nowait returns a control-p, the keyboard poll 
routine toggles the print logging flag and validates the handle for the standard 
printer. If the character is not special, it is returned, and the keyboard poll rou- 
tine exits. 
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Background Processing Dispatcher 


The background processing dispatcher is one of the hooks added to DOS to sup- 
port background applications. This routine is called directly from several Key- 
board I/O routines as well as from the keyboard poll routine. 

If DOS is not currently processing a critical error, the background process- 
ing dispatcher issues an INT 28H request. Programs such as PRINT.COMset up INT 
28H interrupt service routines. When an INT 28H request is received, it is safe to 
perform disk I/O. The DOS character I/O routines call this routine on the user 
I/O stack. If an INT 28Hinterrupt service routine makes a disk I/O request, the INT 
21H dispatcher saves the current stack (user I/O) and switches the disk I/O stack. 
When the disk I/O completes, the INT 21H dispatcher restores the user I/O stack 
and completes the character I/O operation. Support for this feature is the reason 
that the INT 21H dispatcher provides for one level of recursion when it saves the 
caller SS:SP registers. 


Writing Background Programs 
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Stack switching in the INT 21H dispatcher and recording I/O parameters in static 
variable makes the INT 21H service routine nonreentrant. Other kernel services 
including video INT 10H, absolute disk read INT 25H, absolute disk write INT 26H, 
and Diskette/Disk I/O INT 13H also suffer this limitation. DOS is basically a single- 
user, single-program operating system, but it does provide some hooks for back- 
ground programs. 

The architecture of the DOS kernel complicates development of these ap- 
plications. The basic strategy for writing a background program is to load the 
program normally, perform the necessary initialization to deal with reentrancy 
restrictions and to insure periodic CPU access, and finally terminate using the 
DOS TSR request INT 21H (AH = 31H). 

A background program can schedule itself two ways. Keyboard I/O re- 
quests give background programs access to the processor through the undocu- 
mented INT 28H mechanism. Since COMMAND.COM uses these routines for input, 
background programs will get access to the processor while the user interface 
awaits input. 

There is no guarantee these requests will occur frequently enough once an 
application starts up. Background programs normally take over the DOS timer 
interrupt (1cH) as well as INT 28H. Declaring a timer interrupt service routine a 
program guarantees that it will gain access to the processor 18.2 times a second. 

Logic within the background program must decide whether or not it is safe 
for the application to run when called through either of these interrupts. It is 
always safe to proceed if the background program does not need any DOS serv- 
ices, but life is hardly ever this simple. 

The cleanest scheduling algorithm is for the application to run only at 
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those times when any request for kernel service would be safe. Checking the 
INDOS and critical error flags and trapping nonreentrant DOS requests pro- 
vides the application with enough information to make safe scheduling choices. 


Initializing a Background Program 


Until the background program issues its TSR request, all DOS kernel services are 
safe. The initialization code should obtain the address of the INDOS flag through 
the undocumented INT 21H (AH = 34H) request, declare interrupt service rou- 
tines to trap nonreentrant kernel requests INT 25H, INT 26H, and INT 13H, and es- 
tablish INT 28Hand 1cHinterrupt service routines. The interrupt service routines 
for INT 25H, 26H, and 13H merely note that one of these requests is in progress and 
then invokes the original interrupt service routine. 

The DOS kernel uses the recorded address of the current PSP to locate the 
JFT. A background program must establish the correct PSP before performing 
any I/O. When a background program initializes, it must get its own PSP address 
through INT 21H (AH = 62H)or INT 21H(AH = 51H) (undocumented) for future 
use. 

Any other information available through INT 214 requests should also be ob- 
tained at this time, e.g., the address of a device header. Background programs talk 
directly to the driver to avoid INT 21H reentrancy problems or to minimize the 
overhead in dealing with a driver. PRINT.COM uses this technique to pass requests 
to the current print device. An application can get the address of a device header 
by locating the NUL header using the undocumented INT 21H (AH = 52H) get List 
of List address) and walking the device header chain or by using an FCB open. 

After completing any other application-specific initialization, the back- 
ground program issues a TSR request to return control to the user interface. 
The resident portion of the program will periodically get access to the processor 
through either INT 28H (background scheduler) or INT 1cH (timer). 


Deciding Whether to Run 


When the background program is called through one of its interrupt service 
routines, it must decide whether or not it wants to run. Even if it is safe, a back- 
ground program might not want to run. Background programs must be careful 
not to monopolize the processor. 

Certain background operations are inherently safe. No special precautions 
are needed to talk directly to a device driver. If the program is called through INT 
28H, it can issue INT 21H requests which are serviced on the disk stack so long as 
no INT 25H, 26H, or 13H is in progress. If the program gains control through the 
1cH timer interrupt it must check the state of the INDOS and critical error flags 
and verify that none of these interrupts are in progress. 
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Preparing for the Request 


A background program must be careful not to disturb DOS or the current appli- 
cation. It must save any registers that it will modify and initialize its data and 
stack segments prior to running. 

Two significant events can occur in the process of making an INT 21Hrequest: 
a control-c can be detected or a critical error can occur. The background program 
must guard against either of these events by setting up control-c INT 23H and criti- 
cal error INT 24H interrupt service routines. These must be installed any time the 
background application runs. The background program may also want to disable 
break (control-c) checks while it is running. INT 21H(AX = 3302H) is useful for this 
purpose. It exchanges the value in DL with the current break flag. (This particular 
subfunction is undocumented in some versions of DOS.) 

Finally, the application must make sure that the DOS kernel uses the proper 
JFT to process any handle I/O requests. By loading its own PSP with the undocu- 
mented set current PSP INT21H(AH = 50H BX = PSP) segment, the background 
program establishes the proper PSP (and hence JFT). 


Making the Request 


Having made all these preparations, the background application may now safely 
make an INT 21H request. When this request completes, the application must 
undo its preparations and return dismiss the interrupt with an IRET instruction. 


Debugging a Driver 
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Writing a device driver is often easier than getting it to work. Normal develop- 
ment aids such as DE8UG will not work on device drivers. You should debug any 
hardware interrupt service routines as well as the driver strategy and interrupt 
code. The reliance of DEBUG on INT 21H for input and output prevent its use in a 
driver strategy or interrupt routine. Unless special precautions are taken, INT 
21H cannot be used from within a hardware interrupt service routine. (Rest as- 
sured that DEBUG does not take these precautions.) 


Starting with a Stub 


I like to take a top-down approach to driver development. I begin with a minimal 
driver which responds properly to initialization requests and returns a success 
status for all others. I normally use an existing driver as a template for a new 
driver; the “stub” listed in Essay 11 frequently is a good starting point. 
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Debugging the Initialization Routine 


All initialization routines must return an ending (break) address as a status; 
block drivers must return some additional information. If you wish, you may 
print a message from the driver initialization routine using one of the keyboard 
I/O routines INT 21H (AH = 01H to OCH). 

Recall that IBMBIO sends the initialization request to your driver as part of 
the boot process. Errors in your driver can cause your system to hang. You should 
always boot from a removable media when testing a driver. If the boot process 
hangs, reboot with another system disk. Carefully examine the initialization 
code. Make sure that the driver returns a reasonable break address and that 
both the strategy and interrupt routines execute far returns. Both of these mis- 
takes are common driver errors. 


Admiring Your Handiwork 


Once you have successfully booted using your new driver, locate your driver 
code. Make sure your driver really did get loaded and that all its code is intact. It's 
easy to use the incorrect copy of CONFIG.SYS or to load an old version of your 
driver. Returning an incorrect break address does not always hang your system; 
it can cause IBMBIO to overwrite all or part of your driver. 

You can use DEBUG and the List of Lists to locate your driver. The next listing 
shows the sequence used to locate the CLOCK$ driver. I have edited this output 
to fit in this book; your results won't look exactly like those in the listing. You also 
may notice different values in the segment registers on your system. As with the 
previous DEBUG example, user input appears in italics. The commands between a 
and 9104 define and execute a short program. Note that you must end this pro- 
gram with an empty line. (I entered a carriage return in response to the 
152A:0105 prompt.) This program returns the address of the List of Lists in 
ES:BX. The command des:26140 dumps the first 40H bytes of the List of Lists 
which includes the NUL device header. The easiest way to locate this header is to 
look for the string NUL. Working backward from this name, we find the expected 
value of 8004H for the device attributes. This header corresponds to a character 
device that is the current NUL device. The next two commands, d901:0120 and 
d84d:0120 walk backward through the driver chain to the CLOCK$ device. If we 
had wanted to examine driver code, we could have used the DEBUG "u" command 
to disassemble the driver. From the information contained in this header, we find 
that the strategy routine starts at 84D:0012 and the interrupt routine at 
84D:0024. 


-a 
152A:0100 mov ah,52 
152A:0102 int 27 
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152A:0104 nop 
152A:0105 
-9104 


AX=5200 Bx=0026 Cx=0000 DxX=0000 SP=FFEE BP=0000 SI=0000 DI=0000 
DS=152A ES=012E SS=152A CS=152A IP=0104 NV UP EI PL NZ NA PO NC 


152A:0104 90 NOP 

-des:26140 

012E:0020 10 68 sk 
2E 01 98 0O 2E 01 00 00 ~~... sss 

012E:0030 40 08 00 OO EA 07 00 02 Mapas 
00 OO FO OB OO 00 10 10 aDee esa 

012E:0040 O00 00 B1 09 OO 00 06 1A Sal eteis 
CO 00 01 09 04 8018 14 nau nee 

012E:0050 1E 14 4E 55 4C 20 20 20 . »NUL 
20 20 00 90 AS 15 2E 01 wie Meee 

012E:0060 A9 15 2E 01 AD 15 Pere 

~d901:0120 

0901:0000 O00 00 4D 08 GO 20 48 00 Me. K. 
5A 00 01 52 41 4D 44 49 Z..RAMDI 

0901:0010 53 4B 56 44 49 53 48 20 SKVDISK 
20 56 32 2E 30 08 00 00 V2.0... 

~d84d:0120 

0840:0000 OO 00 EA 07 08 80 12 00 aie Jeaeiee 
24 OO 43 4C 4F 43 4B 24 $. CLOCKS 

084D:0010 20 20 50 1E B8 07 08 8E P.8W.. 
D8 89 1E 00 00 8C 06 02 ne 

“q 


Based on the information presented in this chapter, I have written a pro- 
gram (DEVICES) which lists all block and character devices, displays device in- 
formation, and prints cache usage statistics. The device information includes 
attribute information and the addresses of the device header, strategy, and inter- 
rupt routines. DEVICES uses the CDS and the DCBs to locate block devices and 
the device header chain to locate character devices. I prefer using this program 
to DEBUG because it is easier and provides more information. 


Adding Driver Functions 


After I am confident that the initialization code is working, I add other driver 
functions. I like to use a program that calls the driver directly, bypassing the INT 
21H dispatcher. This technique lets me use DEBUG to trace what is happening in 
the driver. 
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The CallDev routine presented in the next listing shows how you can use 
some undocumented features of DOS to locate and call your driver directly. This 
program sends a request header directly to the PRN driver causing the message 
Hello, worldto be displayed. Please note that lines 16, 18, 21, 22, and 23 cannot be 
entered as shown in this listing. I have split these lines so that the listing would fit 
on this page. 

Lines 2-4 reference some include files. The contents of FC8.0EF were given 
earlier in this essay. The other two files are listed at the end of Essay 11. Lines 13- 
15 use an FCB to open the “PRN” device. A successful FCB open returns the ad- 
dress of the device header in one of the reserved FCB fields. Lines 16-24 fill in 
fields in the request header. Lines 25-35 are a bit tricky; they place three ad- 
dresses on the stack and load ES:BX with the address of the request header. 
First, the address of done is pushed; next comes the address of the driver inter- 
rupt entry. The address of the strategy routine is pushed last. The return_far 
macro at line 36 executes a far return to the driver strategy routine. When it 
completes, the strategy routine executes a far routine which transfers control to 
the interrupt routine. The far return in the interrupt code returns us to done. 


_text SEGMENT BYTE PUBLIC ‘CODE’ ; (01) 
INCLUDE FCB.DEF 3; [02] 
INCLUDE DEVICE.DEF ; (03) 
INCLUDE MACROS.ASM ; (04) 
ASSUME cs:_text,ds:_text ; (05) 
ORG 100H ; (06) 
CallDev PROC NEAR ; [O07] 
jmp start ; (08) 
theFCB FCB <, ‘PRN '> ; [09] 
theRH RH_IO < ; [10] 
theMsg DB ‘Hello, world',Odh,OQaH; [11] 
theMsgSiz EQU $-theMsg s [12] 
x x x x 
start: mov ah,OfH ; €13] ah <== FCB open 
lea dx, theFCB s (14] dx <== FCB address 
int 21H ; [15] do it 
mov theRH.RH_B_Length,- 

SIZE RH_IO ; (16) request header length 
mov theRH.RH_B_Unit,O ; [17] unit number = 0 
mov theRH.RH_B_Command,- 

RH_C_Output s (18] function is output 
mov theRH.RH_W_Status,0; (19) initialize status 
mov ax,OFFSET theMsg s (20) add buffer address 
mov WORD PTR - 

theRH.RH_A_TransferAddress,ax ; [21] 
mov WORD PTR - 
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theRH.RH_A_TransferAddresst+2,ds ; [22] 


mov theRH.RH_W_Count ,- 
theMsgSiz s (23] and message size 
mov theRH.RH_W_Sector,0; [24] sector = 0 
mov ax,cs 3; [25] 
mov es , ax ; [26] es <== SEGMENT theRH 
push ax s [27] push SEGMENT done 
mov ax,OFFSET done 3; (28) 
push ax ; [29] push OFFSET done 
mov bx ,OFFSET theRH ; (30) bx <== OFFSET theRH 


lds si, theFCB.FCB_A_DHD; [31] ds:si <== device header 


push ds 3; [32] SEGMENT Int entry 
push {si].DHD_W_InterruptEntry; [33] OFFSET Int entry 
push ds ; (34] SEGMENT Stg entry 
push Csi].DHD_W_StrategyEntry ; (35] OFFSET Stg entry 
return_far ; (36) call strategy routine 
done: mov ah,4cH ; [37] ah <== terminate 
int 21H ; (38) 
caller ENDP 
_text ENDS 
END Cal lDev 


When you use a program such as CallDev, pay particular attention to what 
happens with the index registers and stack pointer. If any index registers change 
across the call, make sure you understand why. Forgetting to save a register or 
restoring registers in the wrong sequence are common errors. It is usually wise 
to single-step through one driver call. Make sure the ret instructions in the strat- 
egy and interrupt routines transfer to the proper place. It is easy to mess up the 
stack by removing the wrong number of saved values. 


Calling Your Driver 


The next step in the testing procedure would be to access the driver through 
DOS. You can use the DOS copy command to test your driver read and write 
routines. 

The copy command uses handles to open, read, and write to a device. The 
INT 21H dispatcher switches to the disk I/O stack to process these requests. So 
long as the new device is not the current StdOut device, you can trace execution 
with INT 21H (AH = 9) messages. The INT 21H dispatcher uses the user stack to 
process keyboard I/O (AH = 1to AH = OcH) requests, and can handle this one 
level of recursion. Note that this capability is not documented and may break in 
the future. 
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If a request appears to complete successfully and DOS dies sometime later, 
it is a good bet that a register was inadvertantly changed or the driver erron- 
eously overwrote some important DOS variable. (Usually any location acciden- 
tally modified by a driver is important to DOS.) The most common cause of 
trashing a DOS variable is improper initialization of a segment register. Some- 
times MASM adds to our confusion by doing something unexpected. You must 
be very careful with ASSUME statements, or MASM may do you in. 

Stack overflow (putting too much information on the stack) or underflow 
(removing too many items from the stack) can also lock up the system. Stack 
errors usually show up very quickly. If stack overflow is suspected, switch to a 
driver-private stack or increase the size of the existing stack. 

Unless your driver makes many subroutine calls or saves a lot of informa- 
tion on the stack, you shouldn't need a separate stack. One reason that the INT 
21H dispatcher switches stacks is to protect DOS from applications with inade- 
quate stack space. It is easy to switch stacks; you load the SS:SP registers with 
the address of a data area within your driver. Of course, you must remember to 
save the original SS:SP values and restore them before your driver returns. The 
SOUND driver described in Essay 11 illustrates this technique. 


Dealing with Hardware Interrupts 


Some devices are capable of generating interrupts. They are a way of getting the 
processor's attention on demand. Your PC has some special hardware to support 
this feature. When a device generates an interrupt, the same event sequence 
that occurs when the processor executes an INT nn instruction is followed. 

There is one important difference between hardware-generated interrupts 
and executing an INT instruction: the hardware interrupt can occur at any time. 
There are times when you don’t want to be interrupted. You must take explicit 
action to avoid an interrupt at an inappropriate time; this process is known as 
synchronization. (See Essay 11 for a more complete discussion of this topic.) 

The PC hardware which supports the interrupt mechanism has some sub- 
tle features which you must be aware of, such as adapters that generate a spe- 
cific interrupt (e.g., O9H) which you must enable. Once an interrupt has been 
generated, it cannot recur until you say it is OK by sending an End of Interrupt 
(EOI) message to the hardware. 

Adapter interrupt service routines are the most difficult part of the driver 
to debug. Many interrupt service routine errors, including improper synchroni- 
zation, tend to be timing sensitive. No BIOS requests can be safely made from an 
interrupt service routine. Diagnostic information can be written directly to 
video memory. This technique is not pretty and may introduce enough delay to 
cause problems or make problems disappear, but it is still worth a try. The 
printer or COM port may also be used when their slow speed will not cause a 
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problem. Interrupt driven I/O should not be used for diagnostic writes. If the 
driver does not work and the system does not lock up, sometimes counters can 
be used to track down a problem. Each time a particular event happens, update 
a counter. Use a debugger to examine these counters later. 

Common interrupt service routine errors include forgetting to send an EOI 
to the interrupt controller, sending too many EOIs, using a RETinstead of an IRET 
to dismiss the interrupt, not enabling a particular interrupt, forgetting to save a 
register, and stack overflow. Devices can generate spurious interrupts and inter- 
rupts can be missed. Heavy duty hardware aids are often needed to track down 
these types of errors. 


Conclusion 


This has been a long journey. We found that in order to understand device driv- 
ers we had to look at most of the interfaces and data structures within DOS. (See 
Essay 6, Undocumented MS-DOS Functions, by Ray Michels, for a reference-type 
approach to DOS internals focusing on undocumented DOS features.) 

The more you know about DOS, the more you can do with it. I have used 
the information presented in this chapter to write self-loading device drivers 
and a utility which loads (and unloads) drivers. The key in this age of networks is 
exploiting the versatility built into DOS. Network devices can be very useful for 
developing applications in a heterogeneous environment. 
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Device drivers are the essential tools that allow your programs to control 
printers, disk drives, sound generation chips, and many other devices. Writing 
or modifying device drivers to accommodate new or improved hardware is an 
important programming task. (See Essay 10, Developing MS-DOS Device Drivers, 
for a comprehensive discussion of the many MS-DOS data structures and serv- 
ices involved with file and device access.) 

Some of the material presented here may be new to you. If your goal is to 
write a device driver after studying this essay, you'll need to know assembly lan- 
guage, understand MS-DOS, and be familiar with digital logic. This knowledge 
comes with experience. Even if you are unfamiliar with 8086 assembly lan- 
guage, don't despair. Although the driver and other examples are coded in that 
language, they are heavily commented, and the accompanying text explains the 
salient features. 

There is a little something for everyone in this essay. The sample device 
driver turns your PC into a musical instrument, so musically inclined readers 
will have fun playing with this infrequently exploited PC capability and using it 
to explore music composition. The more technically minded reader may be in- 
terested in the relationship between DOS and device drivers. The programming 
techniques and performance analysis are useful additions to any programmer's 
bag of tricks. If you really want to write a device driver, the driver code included 
at the end of this essay is a good starting point. Although the best way to learn 
about device drivers is to write one, you can also learn a lot by studying someone 
else’s code. 


Setting up the SOUND Driver 


The SOUND driver is a sophisticated DOS device driver which converts textual 
descriptions to musical tones. Commands can be put into a file and sent to the 
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driver with the DOS copY command or directly written from your own program. 
They support a superset of the functions provided by the well known BASICA 
SOUND and PLAY statements. 

This section describes the organization of the driver software and the steps 
needed to create a working version of the SOUND driver. Please pay special atten- 
tion to the warning in the next section about installing this driver on your hard disk. 
Once I have shown you how to build and install the driver, I will give you an 
example you can use to try it out. 


Creating a Working SOUND Driver 


The six files needed to build the SOUND driver are listed in Table 11-1. Listings of 
these files appear at the end of this chapter. Use EDLIN or a real text editor to 
create these files. You can also use a word processor if it can save documents as 
ASCII text. Most word processors normally imbed format information in the file 
which the assembler (MASM) cannot handle. You need not include the com- 
ments that begin with a semicolon and extend to the end of the line. 


Table 11-1. SOUND Driver Files 
LS SS SS SSS lS SS 


File Description 
-—sggund.asm=—=*é“‘é*S@ riversource=~=~«7TD 
macros.asm Useful macros 
device.def Definitions of device and request headers 
hardware.def Hardware related definitions 
values.def Various driver parameters 
fsm.def Definition of macros for finite state machine 


—_—_—_—_—_—_—-----_—__—_- ee eee 


Create a subdirectory and move all these files to it. Do not name this sub- 
directory SOUND. The driver which you are building is known to DOS by this 
name and its presence will prevent you from accessing the subdirectory. Use the 
following commands to create a working SOUND driver. The link command will 
produce an ignorable warning that there is no stack segment. You now have an 
executable version of the SOUND driver. 


masm sound; 
Link sound; 
exe2bin sound \sound.sys 
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Installing and Using the SOUND Driver 


I have tested this code on IBM XT and AT computers, but you should not assume 
that it will work on your system. The driver may not work on certain hardware 
configurations or in conjunction with programs which manipulate the timer vec- 
tors. You should always test a new device driver by booting from a floppy disk. If 
the driver passes this first test, you can move the driver to your hard disk, but 
make sure you have a bootable floppy disk in case something goes wrong. 

Add the following line to your CONFIG.SYS file and reboot your system. 


device=\sound.sys 


The SOUND driver is now installed and ready to use. 


SOUND Driver Commands and Musical Notation 


SOUND driver commands control music pitch (frequency) and duration. Each 
musical note conveys both pitch and duration information. Individual notes are 
combined to produce a tune. 


Pitch and Musical Notes 


Pitch specification rules are modeled after the piano keyboard shown in Figure 
11-1. (A real keyboard actually has 88 notes.) The SOUND driver can play 84 differ- 
ent notes which are specified by number or name. The command to select a note 
by number is the letter N followed by the note number N13 selects the 13th note. 

The 84 different notes are divided into seven octaves of 12 notes each. An 
octave begins with a note named C, followed by C# (C sharp), D, D#, E, F F#, G, 
G#, A, A#, and B. Each note in this sequence, known as a chromatic scale, is one 
half-step above the preceding one. Moving up one half-step increases a note's 
frequency about six percent. Octaves are numbered from 0 to 6. Moving up one 
octave doubles a note’s frequency. The letter O followed by a number specifies an 
octave. The command 03 selects the third octave, the one beginning with middle 
C. The default octave number is 4 04. 

Middle C is the key in the middle of a piano keyboard. The note located at 
zero NO is the C three octaves below middle C, and its frequency is 1% that of 
middle C. To completely specify a note, either a number or a name and an octave 
is required. The commands 03¢ and N36 both select middle C. Once an octave 
command appears, subsequent named notes are assumed to be in the same oc- 
tave. The sequence 03CDE selects middle C and then the notes D and E directly 
above middle C. 
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Octave 3 (03) 


36 37 38 39 40 41 42 43 44 45 46 47 


Octave 4 (04) 


48 49 50 51 52 53 54 55 56 57 58 59 


Fig. 11-1. The piano keyboard. 


Sharping a note raises its frequency one half-step and flatting it lowers its 
frequency by an equal amount. Sharps are indicated by #or + and flats by -. F# 
says take the note F and raise it one half-step. Both BASICA and the SOUND 
driver support sharps and flats. The SOUND driver accepts double sharps and 
double flats, which raise or lower, respectively, the frequency one whole-step. 
c## (C double sharp) says to raise C one whole-step. Since D is one whole-step 
above C, C## and D are names for the same note. 


Scales and Key Signatures 


Notes are grouped into scales; each note in a scale has a precise relationship to 
the preceding one. There are eight notes in a major scale. The third and eighth 


Chapter 11: A SOUND Device Driver 


notes of this scale are one half-step above their predecessors; all others are sepa- 
rated by a whole-step. Each scale has a name taken from its initial note. The 
simplest major scale is C major whose notes are C, D, E, FG, A, B, and C. Musical 
scores use a key signature to select a scale. If there is no explicit signature, the 
key of C is assumed. The SOUND driver supports multiple keys. The Kcommand 
followed by the key name specifies a key signature; thus, KF# selects the key of F 
sharp. Like the octave command, a key signature remains in effect until it is ex- 
plicitly changed. BASICA does not support key signatures; all music must be in 
the key of C. 

Key signatures affect the interpretation of music. In the key of C, there are 
no sharps or flats, and an F sharp must be explicitly written. The G major scale 
consists of G, A, B, C, D, E, F#, and G. In this key KG, an F is played as F sharp. To 
summarize the effect of a key signature, the sequence KCOOF would select F (N6), 
but KGOOF would select F Sharp (N7). 

If a sharp or flat is needed in a key where the note would not normally be 
played this way, the sharp or flat must be explicitly written. Musicians refer to 
such an occurrence as an accidental. KCF# would explicitly ask for F sharp even 
though that note does not appear in the C major scale. It is sometimes necessary 
to lower a note which normally would be sharped or raise a note which normally 
would be flatted. Another accidental, a natural, is used for this purpose. The 
musical natural symbol does not have an ASCII equivalent; it looks like a square 
box with two tails. The SOUND driver uses = to represent a natural. If a score 
were written in the key of G (F would normally be sharped) and the composer 
wanted a normal F (F natural) played, he must explicitly ask for it. The equivalent 
SOUND driver command would be kGF=. This sequence says play in the key of G 
(KG), but make F unsharped. BASICA does not support naturals. 


Duration 


Three factors control sound duration: length indicated by the note, time, and 
tempo. Each note in a musical score has a relative duration implied by how it is 
written. Scores contain whole-notes, half-notes, quarter-notes, etc. A whole- 
note lasts twice as long as a half-note and four times as long as a quarter-note. 
The length command is used to specify default duration, and is written as the 
letter L followed by a number from 1 to 64. The number 1 corresponds to a 
whole-note, 2 to a half-note, 4 to a quarter-note, 8 to an eighth-note, etc. L, like 
O, applies to all following notes. A number following a note indicates the dura- 
tion of just that note. The sequence 03L4cpCc8 specifies that middle C, D above 
middle C, and middle C be played in succession. The default duration L4 makes 
the first two quarter-notes, but the last note is explicitly labeled as an eighth- 
note. (The duration of eighth-notes is half that of quarter-notes.) The length of a 
note may also be dotted. A dotted length is 50 percent longer than an undotted 
one. The sequence 03L4.CC8. would play middle C first as a dotted quarter-note 


351 


Section 3: Working with the Hardware Interface 


352 


(duration 1.5 times a quarter-note) followed by a dotted eighth-note (duration 
1.5 times an eighth-note). 

Notes may be tied together. In musical notation, notes are tied together by 
connecting them with an arc—the notes must be the same. The arc is also used 
to indicate something called a slur. Tied notes are played as one; the duration is 
the sum of the individual note lengths. The command 03¢18&C1 says play middle C 
for twice the normal duration of a whole note. BASICA does not support ties. 

A second factor affecting note duration is time which indicates how many 
beats per measure and what type of note gets one beat. Musical scores are di- 
vided into units called measures which contain an equal number of beats; graph- 
ically, measures are indicated by vertical bars. If no time is explicitly indicated, a 
score is assumed to be in 44 time which means there are four beats to a measure 
and a quarter-note gets one beat. Neither BASICA nor the SOUND driver support 
times; however, they could be easily added to the SOUND driver. 


Time and Tempo 


Tempo is the third factor affecting note duration. Tempo specifies the absolute 
speed at which a score should be played. Composers specify tempo by indicating 
that so many of a particular type of note (e.g., quarter-note) must be played in a 
minute. The note type used to set the tempo depends on the time of the music; 
BASICA and the SOUND driver use quarter-notes. The tempo command, written 
as Tfollowed by a number, specifies how many quarter-notes must be played ina 
minute. The default tempo, 1120 says that 120 quarter-notes must be played in 
one minute. Some scores use a less precise method of specifying tempo. Words 
like andante (slowly), moderato (moderately), and presto (fast) are used to select 
a range of tempos. Andante indicates a tempo range of 76-108 quarter-notes per 
minute, moderato a tempo of 108 to 120, and presto a range of 120-168. 

Rests indicate periods of silence. There are whole-rests, half-rests, quarter- 
rests, etc. These individual rests select different periods of silence. BASICA uses 
the pause command, P, to indicate a rest. Syntactically, the pause command is 
treated like a note (except that it cannot be sharped or flatted). The commands 
p4 and L4P would both indicate a quarter-rest. 


Staccato and Legato 


Both the SOUND driver and BASICA provide three commands which crudely deter- 
mine the way music is played. MNasks for ‘normal’ mode, MS selects “staccato” mode, 
and ML “legato” mode. Music style is implemented by varying the time between 
notes. (It should be noted that the BASICA implementation used incorrect values 
for this internote pause.) When a musician changes from one style to the other, he 
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is able to vary volume and harmonic content of the note as well. The sound genera- 
tion hardware in the IBM PC/XT/AT is rather primitive compared to a musical in- 
strument. The SOUND driver does not support foreground MF and background mB 
playing. 

The SOUND driver supports imbedded comments. A comment begins with 
an exclamation point (!) and terminates at the end of a line. The delimiter and 
any subsequent characters are ignored. Comments can be used to imbed lyrics 
or titles in a tune file; they are not supported by BASICA. 


Command Summary 


Table 11-2 summarizes the SOUND driver commands. Asterisks indicate SOUND 
driver enhancements not found in BASICA. Notes (A . . . G) can have trailing ac- 
cidentals (#, ##, +, + +, —, - —,or =). A dotted length may follow the note 
name or pause. 


Table 11-2. SOUND Driver Command Summary 
Se SSS SS SSS SSS 


Command Description 

- Flat 

-- *Double flat 

# Sharp 

## *Double sharp 

+ Sharp 

++ *Double sharp 

= *Natural 

& *Tie 

! *Comment 

. Increases duration by 50 percent 

A...G Note 

Kxx *Key signature (xx = valid key name) 

Lnn Note length (1 ¢ = nn ¢ = 64) 

ML Music legato 

MN Music normal 

MS Music staccato 

Nnn Note number (0 ¢ = nn ¢ = 83) 

On Octave (0 (= n (= 6) 

P Pause 

Tnnn Music tempo (30 ¢ nnn ¢ 300) 
Using the SOUND Driver 


The first step in using the SOUND driver is to convert a musical score to driver 
commands. Figure 11-2 illustrates this process for the first 11 notes of “Mary Had 
a Little Lamb.” 
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These notes 

are in 

Octave 3 (E flat) (eighth rest) 
Oo3 T100 L8 G F &-& F G GG P F F_ F4 


Fig. 11-2. “Mary Had a Little Lamb.” 


If you create a file named TUNE.DAT which contains these commands, you 
can “play” it with the DOS copY command. COPY TUNE.DAT SOUND. Using the SOUND 
driver in this way is like playing a record. You start it with the Copy and music 
continues until the entire file has been processed. 

Interactive access to the driver is also possible with commands from the 
keyboard. Again we use the DOS copy command, but this time we copy our key- 
board input to the driver. Enter the command Copy CON SouND and then enter the 
commands and notes you want performed. Either a control-z or F10 terminates 
the interactive mode. (Both these keys generate an end of file character.) You may 
find this technique a bit awkward because a note will not start to play until the 
first character of the next note is entered. 

You can also access the driver directly from your own program. The follow- 
ing program plays the first 11 notes of “Mary Had a Little Lamb.” 


_data SEGMENT WORD PUBLIC ‘DATA’ 

notes dB 'TI00L803GFE-FGGGPFFF4' 

num_notes EQU $-notes 

sound DB "SOUND' ,O 

_data ENDS 

_Stack SEGMENT WORD STACK ‘STACK’ ; "exe" programs 
DW 256 DUP(O) s need a stack 

_stack ENDS s segment 

_text SEGMENT BYTE PUBLIC ‘CODE’ start of segment 


; 
ASSUME cs:_text, ds:_data ; needed by masm 


start PROC NEAR 3; start of procedure 
mov ax, data 3; "exe" programs must 
mov ds,ax s initialize ds 
mov dx,OFFSET sound ; dx == addr( sound ) 
mov ax,3d01H s ask DOS to open device 
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int 21H ; for write 
mov bx, ax 5 bx == handle 
mov dx,OFFSET notes ; dx <== addr( notes ) 
mov cx,num_notes ; cx <== # characters 
mov ah, 40H : ask DOS to write these 
int 21H ; characters 
mov ah,3eH ; ask DOS to close device 
int 21H 
mov ah,4cH ; ask DOS to terminate 
int 21H ; program 

start ENDP : end of procedure 

_text ENDS ; end of segment 
END start ; specify start address 


You may wish to transcribe printed sheet music into input for the SOUND 
driver. This takes a little practice, but it’s not really hard. As an example, Figure 
11-3 illustrates the score to Beethoven's “Ode to Joy” from the last movement of 
his Ninth Symphony. This listing shows the resulting transcription: 


KDT12003 L4F2GAAGFEDDEFF.E8E2 
FFGAAGFEDDEFE.D8D2 
E2FDEF8G8FDEF8G8FEDEOZA03F& 
FFGAAGFEDDEFE.D8D2 
O4F2GAAGFEDDEFF .E8E2 
F2GAAGFEDDEFE.D8D2 
E2FDEF8G8FDEF8G8FEDEOSA04F& 
FFGAAGFEDDEFE.L8DDAGFL4 
E2FDEF8G8FDEF8G8FEDEOSAO4F& 
FFGAAGFEDDEFE.D8DP4 


The SOUND driver maintains an internal buffer (currently 256 notes). Music will 
continue to play after the copy completes or the device is closed. 


Hardware Review 


Before we get into the details of writing our SOUND driver, let's consider how the 
relevant PC hardware is accessed by a device driver. The hardware which con- 
trols a device may exist as a separate board called an adapter or may be part of 
the mother board. The board designers provide one or more ports for the CPU 
to communicate with the device. You can think of these ports as a mailbox. 
When the CPU wants to tell the device something, it places a message in this 
mailbox. Similarly, when a device has information for the CPU, it leaves a mes- 
sage in this mailbox. The hardware helps keep track of sender and receiver. 
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Ode to Joy 


Fig. 11-3. Beethoven's “Ode to Joy.” 


Some of these devices can perform more than one function. The CPU re- 
quests a particular action by sending appropriate data to the device. You can 
think of what is being sent as a program that the CPU wants the device to exe- 
cute. The device returns the results of this program to the CPU as a status. Mes- 
sages placed in these mailboxes may be programs, data, or status. 


Controlling a Device 


Intel processors use special instructions to communicate with a device. All mem- 
bers of the 80X86 provide IN and ouT instructions. Some have special instruc- 
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tions for reading or writing more than one byte at a time. The IN and OUT 
instructions move data between the accumulator and the port whose address is 
in the DX register. 

On the IBM PC, COM1 is implemented with an INS8250 UART chip. This 
chip has several ports. The next listing shows a simplistic approach to reading a 
character from COM1. Characters are read by specifying the receive buffer 
pointer as the target of an INinstruction. Actually dealing with COM1 is slightly 
more involved. We want to read each character only once. The 8250 sets a bit in 
another register to indicate that a character is available and clears this bit after 
the receive buffer register is read. 


coM1 EQU 3f8H Base for COM1 


fi 
RBR EQU 0 + Receive buffer register 
3; offset 
mov dx, COM1.RBR 3; dx <== addr( RBR ) 
in al,dx ; read the character 


The following example shows how you might actually read a character from 
COM1. I've omitted some important details from these examples such as establish- 
ing communications parameters (speed, parity, etc.) and checking for errors. 


com1 EQU 3f8H Base for COM1 


=a 


RBR EQU 0 ; Receive buffer register 
; offset 
LSR EQU 5 ; Line status register 
; offset 
DR EQU 1 ; Data ready flag 
mov dx,COM1.LSR 3; dx <== addr( LSR ) 
wait: in al,dx ; read line status 
and al,OR ; hew character? 
jz wait ; if Z--not yet 
mov dx ,COM1.RBR 3 dx <== addr( RBR ) 
in al,dx ; read the character 


Interrupts Explained 


The INS8250 is relatively slow compared to the CPU. The processor will execute 
many instructions while it waits for a character to arrive. In the previous exam- 
ple, the CPU is doing nothing useful while it awaits the next character. Some- 
times we will not want to waste this time. Interrupts help the PC deal with this 
problem. If a device wants to get the processor's attention (as COM1 would when 
a character arrived), it can request an interrupt. Under certain conditions, the 
processor stops what it is doing and deals with the interrupt. 
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A special chip, the 8259 Interrupt Controller, helps the processor deal with 
interrupts. This chip controls when an interrupt is serviced and what code will 
be used to service it. The CPU programs the 8259 by writing control words to 
one of its registers. 

The 8259 deals with up to eight separate devices and assigns a priority to 
each one. If more than one interrupt has been requested, the 8259 services the 
one with highest priority first. Once an interrupt begins, no lower priority inter- 
rupt can occur until the current one completes, but a higher priority interrupt 
can suspend the one currently in progress. 

The code that gets executed as a result of an interrupt is known as an inter- 
rupt service routine. When the processor grants an interrupt, it pushes the 
processor flags, CS, and IP registers on the stack and transfers control to the 
interrupt service routine. 

When the interrupt service routine begins, all interrupts are disabled. Nor- 
mally, it will enable interrupts almost immediately. Once interrupts are enabled, 
this routine can be interrupted by higher priority interrupts. 

This routine must send the 8259 a control word which indicates that the 
interrupt has been serviced. Normally, this notification occurs just prior to re- 
turning to the interrupted code with an IRET instruction. The following code 
illustrates a typical interrupt service routine. 


18259 EQU 20H ; Base address 
PortA EQU 0 ; Port offsets 
PortB EQU 1 
EOI EQU 20H ; Nonspecific end of 
3; interrupt 
ISREntry PROC FAR 
STI Enable higher priority 


me we 


interrupts 


Normal ISR Logic: 


=e me me 


(1) Save any registers needed by this routine 
(2) Deal with interrupt 
(3) Restore registers saved in step 1 


=. 


=e Se oe 


mov 18259. PortA,EOI ; Say interrupt is over 
iret 3 pick up where we left 
; off 
ISREntry ENDP 


The CPU must explicitly enable individual interrupts by sending a control 
word to the 8259. It can also disable all interrupts with a CLI instruction. The CLI 
inhibits interrupt recognition until the CPU executes a STI instruction. (There is 
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a special interrupt which is not masked by the CLI instruction, but it is not rele- 
vant to our discussion.) 


Programming Techniques 


The SOUND driver uses circular buffers, coroutines, and finite state machines. 
It also illustrates synchronization and critical sections. Although these tech- 
niques are normally discussed in advanced computer science courses, they are 
frequently used in system software. Their names may sound exotic, but these 
techniques are useful and easily implemented. 


Circular Buffers 


Circular buffers are useful when data is gathered and removed at unpredictable 
rates. Their implementation requires a storage area, two pointers, and a flag. 
One pointer specifies where the next data item will be stored and the other iden- 
tifies which item will be removed next. Data is used FIFO (First In, First Out). 
Each pointer initially points to the beginning of the storage area. As data is 
added and removed, each pointer sweeps sequentially through the storage array. 
At the end of the array, the pointer “wraps’ to the first location, hence the name 
circular buffer (see Figure 11-4). 

You can think of this structure as an ordinary array whose beginning and 
ending location “float.” The ending location changes as data is added, and the 
start changes as data is removed. Each pointer can wrap because the start of the 
array floats. If we did not allow the beginning location to float, we would have to 
slide the contents of the buffer down every time we removed an element, which 
would be time-consuming. 

The only trick to implementing a circular buffer is distinguishing between 
the empty and full states. If we use only two pointers and completely fill the 
array, we cannot tell whether the buffer is empty or full. Leaving one location 
unfilled or using an auxiliary variable will solve this problem. The auxiliary vari- 
able may be either a boolean or a buffer count. Here is a program that uses a 
buffer count to distinguish between full and empty: 


BUF_S_Size EQU 8 

_data SEGMENT WORD PUBLIC ‘DATA’ 

BUF_A_Remove DW BUF_T_Data ; Both remove and insert 

BUF_A_Insert DW BUF_T_Data ; initially point to 1st 
3; location 

BUF_B_ Count DB 0 ; No elements initially 

BUF_T_Data DB BUF_S_Size DUP(O) 
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Arriving Data 
6 § 4 3 


Remove 
here 


Fig. 11-4. Circular buffer. 


BUF_A_End EQU $ ; So we can detect wrap 

_text SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME cs:_text, ds:_data 

CirBuf PROC NEAR 

b_succ clc 3; Say we succeeded 
ret : and returned 

berr  stc s Say we failed 
ret 3 and return 

’ 

: Inserts byte in AL into circular buffer. Returns with 

: CY=1 if failed (buffer full) or CY=0 otherwise. 

; 

Insert LABEL NEAR 


cmp BUF_B_Count,BUF_S_ Size 
jz b_err 

xchg bx,BUF_A_Insert 

mov BYTE PTR Cbx],al 


call NextBX 

xchg BUF_A_Insert,bx 
inc BUF_B_Count 

jmp SHORT b_succ 


me =e we =e =e =. we ma 
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Is buffer full? 


If Z--yes 
bx <== insert address 
Insert it 


Calc next address 
Update insert ptr 
One more data item 
Take success exit 


e 
: Removes byte from circular buffer. Returns with CY=1 
; if failed (buffer empty) or CY=0 and AL=byte otherwise. 


Remove LABEL NEAR 


cmp BUF_B_Count,0 
jz b_err 

xchg bx ,BUF_A_Remove 
mov al,BYTE PTR [bx] 


call NextBXx 

xchg BUF_A_Remove, bx 
dec BUF_B_Count 

jmp SHORT b_succ 


NextBX PROC NEAR 


inc bx 

cmp bx, BUF_A_End 

jnz aQ 

lea bx,BUF_T_Data 
a0: ret 


NextBX ENDP 
CirBuf ENDP 
_text ENDS 


Coroutines 


=e =e me 


=e te we BO & 


es GS Ge Be 


Is buffer empty? 
If Z--yes 
bx <== remove address 


; Remove byte 


Calc next address 
Update remove ptr 
One less data item 
Take success exit 


Advance to next item 
Have we reached end? 
If NZ--no 

Wrap the pointer 

and return 


The familiar programming technique of subroutines is a special case of a more 
generalized construction known as a coroutine. The difference between a sub- 
routine and a coroutine is that a subroutine is always invoked at its entry point 
and a coroutine is invoked at the instruction following the one last executed. 
This concept is confusing until you understand the linkage mechanism. When a 
coroutine gives up control, it issues another call rather than executing a return. 
This second call leaves the address of the next instruction on the stack. 
Coroutines are normally quite complex, and it is difficult to come up witha 
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short example that could not be done more easily with some other technique. 
The following listing uses coroutines to decompress run length encoded data. In 
this trivial example, the data consists of zeros and ones. Frequently data con- 
tains runs of the same value. Inserting a run length and single value in place of 
the original run reduces storage requirements. (This technique is common in 
image processing.) The string 0000111011111000000 would be encoded as 


403105160. In this example, the run length must be nine or less. 


lea si,string ; si <== compressed string 
call Dcmprss ; set up initial coroutine 
nxtch: pop bp : bp <== callback address 
or al,al s end of string? 
jz done 3; if Z--yes 
; 
. We pass through here once for every character in the 
; decompressed string. The character (0 or 1) is in AL 
; 
call bp ; make coroutine callback 
jmp SHORT nxtch s get the next character 
done LABEL NEAR s end of string reached 
; 
: ‘ 3; additional processing 
; 
Demprss PROC NEAR 
pop bp 3; bp <== callback address 
; 
: Branch here to look for single value or run 
; 
do: lodsb al <== next byte of 


cmp 
jg 
call 


=e =e =e 


jmp 


s_run:  cbw 
mov 
sub 


al,'1' 
run 
bp 


SHORT Demprss 


Branch here at start of 


CX, ax 


Return here if not in the 


=e =e =e 


compressed string 

is it a run Length? 

if G--yes 

make coroutine callback 


middle of a run 

get another character 
run 

convert run length to 


binary integer 
(ascii to binary conversion) 


Chapter 11: A SOUND Device Driver 


lodsb ; al <== repeated byte 
Branch here to resume run processing 


run: push ax 3; save repeated value 
call bp : make callback 


Return here to continue processing a run 


=e me =e 


pop bp bp <== callback address 
pop ax recover repeated value 
loop n2 continue processing run 


jmp SHORT dO look for run length or 


single value 


me =e me me =e 


Demprss ENDP 


The advantage of using coroutines in this example is that the calling pro- 
gram is unaware of the run length decompression. The decompression routine 
Demprss uses the program counter to maintain state information implicitly. The 
callback address which Demprss leaves on the stack indicates whether or not a 
run is being processed. 


Finite State Machines 


Finite state machines are common in compilers, communications protocols, and 
pattern-searching. They provide a way of dealing with data that must be proc- 
essed according to certain rules or that must arrive in a predetermined se- 
quence. Finite state machines manipulate abstract entities called tokens which 
may be characters, words, sentences, or program statements. The collective set 
of sequencing rules is called a grammar. A token may be acceptable at one time 
and not at another. The grammar specifies when a token is acceptable. The set 
of all possible tokens is called the alphabet. 

A finite state machine is in a particular state while it is waiting for a token. 
When the token arrives, the finite state machine checks to see if the token is 
acceptable. The grammar specifies when a particular token arriving at a given 
time conforms to the rules. If the token is acceptable, the finite state machine 
makes a transition to a new state where a different set of tokens may be legal. (It 
may also stay in the same state.) 

The SOUND driver uses a finite state machine to recognize the sequences 
MN, MS, and ML (see Figure 11-5). In fact, it uses a state machine to recognize all 
sequences. In this case, the alphabet consists of the letters L, M, N, and s. The 
state machine immediately rejects a token which is not in its alphabet. The finite 
state machine initially looks for an M, in this first state, the only legal token. The 
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arrival of an M causes a transition to a new state where N, S, or L are acceptable. 
The arrival of one of these three letters causes the finite state machine to accept 
or recognize the string. It is common to use a picture to represent what happens 
in a finite state machine. Figure 11-5 describes recognition of the MS, MN, and ML 
sequences. Circles represent states and arcs represent transitions. Arcs are la- 
beled with the token which causes the transition. Some arcs are not labeled. 
After recognizing ML, MN, or MS, the state machine in this example resets itself. It 
is then ready to look for another M. 


Synchronization 


Cooperation is needed when multiple processes work on the same problem. If 
we were to write two separate programs—one which inserted characters into a 
circular buffer and another that removed them—we would immediately recog- 
nize the importance of this requirement. The program which removes charac- 
ters must recognize an empty buffer, and the program which inserts characters 
must be smart enough to deal with a full buffer. This scenario is the basis for a 
classical computer science problem, the Producer-Consumer Problem, which is 
solved by synchronization. The consumer, in this case, the remove routine, must 
wait for a new character if the buffer is empty. Similarly, the producer must wait 
for a character to be removed if the buffer is full. Each program can use the 
buffer count to stay in sync with its partner. 

The same problem also occurs in a single program with multiple execution 
threads such as interrupt-driven device drivers. A program which fills a circular 
buffer at a noninterrupt level and removes characters from within an interrupt 
service routine has two execution threads. 

Relegating an execution thread to an interrupt service routine adds an in- 
teresting twist to this problem. The producer, which operates at the noninter- 
rupt level, can enter a busy wait loop if it finds the buffer full. At some time in the 
future, an interrupt will occur and the consumer will remove a character. After 
the interrupt is dismissed, the producer will notice that the buffer is no longer 
full and insert its character. The consumer cannot use this strategy. Since it is 
operating at an interrupt level, the consumer blocks the producer's execution. A 
busy wait loop in the interrupt service routine (see the next example) would 
never terminate, resulting in a condition known as a deadlock. The consumer 
must dismiss the interrupt and depend on the consumer to somehow cause an 
interrupt after it places a character in the buffer. 


test: cmp count,size s is the buffer full 
jz test ; if Z--yes 


There's at least one empty location now. 


=e we we 
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ae ea, 
= ben % 


Not 


Fig. 11-5. Finite state machine. 


Critical Sections 


The following example illustrates what happens when two execution threads 
try to alter a common variable: 


noninterrupt level code 


=e Ge BO 


fa] put value in accumulator 


mov ax, value ; 
add ax,10 s [b] make an adjustment 
mov value,ax ; Cc] update value 


me =e me 
e 
e 
e 


Interrupt service routine 


mov ax, value 
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sub ax, 10 
mov value, ax 


If an interrupt occurs after [a] but before {c] completes, the alteration made 
in the interrupt service routine will be overwritten as [c] executes. For these two 
code fragments to work correctly, no interrupts can occur between the load and 
store instructions. This requirement of guaranteed completion is known as a 
critical section. Disabling interrupts before [a] and enabling them after [c] in- 
sures correctness. 

We don’t always have to disable interrupts when two threads update a 
shared variable. The previously discussed circular buffer routines may be called 
from different execution threads. Both routines alter BUF_B8 Count, but this ad- 
justment occurs within a single, indivisible instruction. Once the INC or DEC in- 
struction begins, it is guaranteed to complete. 

There are potential critical sections in these routines. If Insert is called at 
both the interrupt and noninterrupt levels, the BUF_A_Insert may be corrupted. 
(Consider what happens if the interrupt occurs between the two xchg instruc- 
tions.) Changing where the buffer count is updated will introduce a critical sec- 
tion. If BUF_W_Count were changed before BUF_A_Insert or BUF_A_Remove was 
updated, the wrong buffer element might be removed. (Look at the buffer full 
and buffer empty cases.) 

Identifying and dealing with critical sections is a very important part of 
writing a device driver. When handled incorrectly, critical sections often result 
in nasty bugs that can be very difficult to isolate. You'll see examples of critical 
sections in the SOUND driver. 


DOS Internals 
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In this section, we will review driver structure and DOS/driver interaction. You can 
find more complete descriptions of this material in the Disk Operating System Tech- 
nical Reference Guide (1984), the MS-DOS Technical Reference Encyclopedia (19886), 
the MS-DOS Developer's Guide (Angermeyer et al. 1986), and in Essay 10 of this book. 

Every device driver has three parts—device header, strategy routine, and 
interrupt routine. Whenever DOS needs to access a device, it creates a structure 
called a request header and passes its address to the driver, which uses it to re- 
turn status information to DOS. 


Device Header 


The device header supplies a device name, a summary of driver capabilities, and 
the addresses of two driver entry points. The following example illustrates the 
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header. Because of the way in which DOS loads device drivers at boot time, the 
device header must be at the beginning of the driver. 


DHD STRUC 

DHD_A_NextDHD DD <4 :; Address of next device 
DHD_W_Attrib DW 0 2:3 Device attributes 
DHD_W_SrategyEntry DW 0 33; Strategy entry offset 
DHD_W_InterruptEntry DOW 0 $3; Interrupt entry offset 
DHD_T_Name DB 8 DUPC’ ') 

DHD ENDS 


DOS builds a linked list of device headers. The head of this chain is the NUL 
device, and each DHD_A_NextDHOfield contains the address of the next header in 
this chain. The DHD_W_Attrib field identifies the driver as block or character, de- 
scribes the driver's ability to respond to optional requests, and specifies certain 
special devices. The next two fields specify the offsets for the strategy and inter- 
rupt entry points. Since these fields are only 16 bits, both entry points must be in 
the same segment as the header. The final header field contains the name of a 
character device. Although IBM documentation and various other sources sug- 
gest that block drivers set the first byte of the name field to a unit count, DOS 
does not use this value. 


Strategy Entry 


The strategy entry currently does very little. When DOS needs to access a de- 
vice, it passes a request header to the driver strategy entry which stores this 
address and returns. 


Interrupt Entry 


The real work of completing the request happens in the interrupt entry code. 
This code recovers the address of the request header and completes the re- 
quests. In most cases, the interrupt entry code sets the status field of the request 
header to indicate the results of its processing. 


Request Header 


DOS constructs a request header like the one illustrated in the next example to 
describe a driver request. This structure is not sufficient to describe all possible 
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driver requests. DOS appends information to this basic structure for certain re- 
quests. 


RH STRUC 

RH_B_Length DB 0 73 Length (bytes) of this 
$3; request header 

RH_B_Unit DB 0 s3 Unit code 

RH_B_Command 0B 0 :3 Command code 

RH_W_Status DW 0 77 Operation results 

RH_T_ReservedDOS DB 8 DUP CO) 

RH ENDS 


RH_B_Length specifies the total length of the request header. DOS always 
sets this field, but it is never used. A block device driver can control multiple 
units. The RH_8_Unit field identifies which unit is the target of the request. DOS 
keeps track of the driver address and unit number for each block device. 
RH_B_Command specifies the requested operation. The driver normally sets 
RH_W_Status to indicate the results of an operation. This field is also used to indi- 
cate that a device is busy. 


IOCTL Requests 


A BIOS call initiates IOCTL requests which allow direct device control and ac- 
cess to device status information. The next example demonstrates this tech- 
nique. DOS can satisfy some of these requests without driver intervention and 
supports them regardless of the state of the IOCTL bit. Get and set device infor- 
mation (AL = 0 or AL = 1) manipulates DOS tables. The set function can 
change mode as well as current standard input and output. These operations 
affect the way DOS passes requests to the driver (see Essay 10). DOS sends input 
and output status requests to the driver in response to IOCTL status operations. 


; there are several functions 
; (see Tech ref manual) 
; BIOS IOCTL request 


mov al, function 


mov ah, 44h 


Request dependent info in BX and CX 


=e me =e 


int 21H s issue BIOS request 


Other requests require explicit driver support. The driver indicates it is 
able to handle these requests by setting the IOCTL bit in the device attributes 
word. If this bit is set, DOS creates the appropriate request header and passes its 
address to the driver, which is free to interpret these requests as it sees fit. 


Prototype Driver 
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The prototype character driver upon which the SOUND driver is built does no 
useful work. It returns a successful status for each character device operation 
and an error status for all others. Code for this prototype driver is listed next. 
Because it is so simple, the prototype driver is a good introduction to my pro- 
gramming style and driver structure in general. 


ff 


TITLE DriverStub 
INCLUDE MACROS.ASM 
INCLUDE DEVICE.DEF 


7) =e 


useful macros 
Driver data structures 


DHD_M_Character OR DHD_M_IOCTL 


dFlags 


_ff OR DHD_M_OCRM 


_text SEGMENT BYTE PUBLIC ‘CODE’ 


ASSUME 
ORG 
Driver PROC 


cs:_text,ds: text 
OOH ; Drivers begin at OOH 
NEAR 


begin: DHD <-1,dFlags, StgyEntry, IntEntry,'SOUND '> 


RQ_T_Table: 
DW 
OW 
DW 


DW 
DW 
OW 
DW 
DW 
DW 
DW 
DW 
OW 


DW 
DW 
DW 
OW 
DW 


SoundInit 
SoundNoP 
SoundNoP 


SoundInIOCTL 
SoundError 
SoundError 
SoundError 
SoundError 
SoundWrite 
SoundWrite 
SoundStatus 
SoundF tush 


SoundNOP 
SoundOpen 

SoundC lose 
SoundNoOP 
SoundWriteTi lBusy 


=e me =e =e =e me =e =e =e =e =e =e =e 


=e @e Be BRE BO 


Device Initialization 
Media check 

Build BIOS parameter 
block 

Input IOCTL request 
Input (read) request 
Nondestructive input 
Input status 

Input Flush 

Output (write) 
Output write verify 
Output status 

Output flush 


Output IOCTL request 
Device open request 
Device close request 
Removable media 
Write until busy 
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RQ_S_Table = (RQ_T_Table-$)/2 

DW 256 DUP(O) ; Private stack for driver 
DriverSP DW $-2 ; Current top of stack 
Dosss DW 0 ; DOS stack segment 
DosSP DW 0 ; DOS stack pointer 
RqOffset DW 0 3; OFFSET of request hdr 
RqSegment DW 0 3; SEGMENT of request hdr 


SUBTTL Process Driver Requests 
DriverRequest PROC NEAR 


SoundError: 
mov ax ,DHD_C_ErrUnknownCommand 
ret 


SoundNOP: 
SoundInIOCTL: 
SoundWrite: 
SoundWriteTi lBusy: 
SoundStatus: 
SoundF Lush: 
SoundOpen: 
SoundC lose: 
mov ax,DHD_M_StsDone 
ret 
DriverRequest ENDP 


PAGE 
SUBTTL DOS Entry Points 


DriverExit: 
les bx,DWORD PTR RqOffset ; ES:BX <== DOS request 
mov es:Cox].RH_W_Status,ax ; Return status to DOS 
mov DriverSP,SP ; Save driver stack 
mov SS,DosSS ; Restore dos stack 
mov SP,DosSP 
popf ; Restore processor flags 
pop_all ; Restore all registers 
return_far ; and return to DOS 
StgyEntry: 
mov CS:RqgOf fset, bx ; Save request address 
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and return to DOS 


Say command is bad 


Save all registers 
Save processor status 
Set driver DS 

(DOS currently does 
this for us) 

Save DOS stack 


Establish driver stack 
Restore driver SP 

Set direction flag 
ES:BX <== DOS Request 
AL <== command 

Is it in range? 

If GE--out of range 
Make command a word 
Convert to word index 
SI <== function table 


Dispatch on function 


mov CS:RqSegment,es 
return_far ; 

IntErrors: 
mov ax,DHD_C_UnknownCommand ; 
jmp SHORT DriverExit 

IntEntry: 
push_all . 
pushf ; 
mov ax,cs : 
mov ds, ax . 

: 
mov DosSS,ss ; 
mov DosSP,sp 
mov SS,ax ; 
mov sp,DriverSP : 
cld ; 
les bx,OWORD PTR RqOffset : 
mov al,es:Cox].RH_B_Command ; 
cmp al,RQ_S_ Table : 
jge IntError : 
cbw : 
add ax, ax : 
mov si,ax ; 
3; index 

call RQ_T_Tablelsi] ; 
jmp DriverExit 

SoundInit: 
mov WORD PTR es: (bx].RH_A_Break, OFFSET SoundInit 
mov WORD PTR es: (bx+2].RH_A_Break,cs 
mov ax,DHO_M__StsDone 
ret 

driver ENDP 

_text ENDS 
END begin 

Coding Style 


In some of the previous code fragments you may have noticed variable names of 
the form XXX _Y__Zzzzzz. These names arise from the technique I use to label 
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data structures. Each of these structures has a 2- to 5-character name which is a 
prefix to the name of a structure element. One of the type-specifiers listed in 
Table 11-3 follows this prefix. The final part of each name identifies an individual 
field. Underscores separate these components. For example, the DHD structure 
defines the device header. The attributes field of the header is a word; the com- 
plete field name is DHD_W_Attrib. 


Table 11-3. Naming Conventions 


Specifier Meaning 


A Address 

Byte Field 

Constant (Byte or Word) 
Mask (Bit field) 

Size of a structure 

Text Field (arbitrarily long) 
Bit Number 

Word (2-byte) field 


S<4ezgoo 


You may notice that comments begin with one, two, or three semicolons. 
Normal comments begin with a single semicolon. I use double semicolons in 
macro definitions to suppress comments in their expansions. Whenever inter- 
rupts are disabled, I begin comments with three semicolons to remind myself of 
the interrupt state. 


Driver Structure 


The prototype driver begins with references to two include files. These two files, 
which I include in every device driver, define MASM STRUCs and macros, and ap- 
pear in the listings at the end of this essay. (See Essay 5, Advanced MASM Tech- 
niques, by Michael Goldman, for more information on STRUCs and macros.) 

The MACRO. ASM file includes definitions for push _all and pop all. Perform- 
ing these operations in a macro ensures that I save all the registers and restore 
them in the correct order. It is easy to forget to save a register or to restore one 
out of order. Macro definitions for explicit near and far returns are also defined 
in this file. On more than one occasion, MASM has generated a near return 
when I really wanted a far return. Of course, this error was one that I created, 
but the macro definitions prevent MASM from helping me make mistakes. 

The DEVICE.DEF file defines the device and request headers as well as speci- 
fying symbolic values for the various fields within these structures. 

Data declarations follow the include statements. The first declaration is the 
device header which begins at or6 0. The PSP causes normal applications to start 
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at ORG 100H, but the driver does not have a PSP. A dispatch table follows the 
header. It is a very common practice to have separate routines for every driver 
function and to use the request code RH_B_Command as an index into a table of 
routine addresses. 

Driver code follows the data section. Notice that the code and data are in 
the same segment. Although separate segments are possible, it is common to 
combine code and data into a single segment. 

The strategy code records the request header address and returns. The real 
work happens in the interrupt code, which saves all registers and the current proc- 
essor flags, sets up the driver data segment, switches to a private driver stack, and 
dispatches on the request code. After completing all request-specific processing, 
the driver returns a status in the request header and restores all registers. 


Sound Generation Hardware 


The remainder of this chapter deals specifically with the SOUND driver. The 
SOUND driver manipulates sound generation hardware and the system clock. 
Before I could design the SOUND driver, I had to understand how this hardware 
worked. 


Sound Generation 


A frequency generator, filter, and speaker make up the sound generation hard- 
ware. The square wave output of the frequency generator drives the speaker 
through a filter (see Figure 11-6). 

The PC uses an 8253-5 programmable interval timer as the frequency gen- 
erator. This chip can perform different functions depending on its initialization. 
The frequency generator divides a 1.139180MHz fixed-frequency, square-wave 
clock input by a software selectable 16-bit value. To produce the A above middle 
C (440Hz) you would load a value of 2712 (1,193,180 + 440) into the counter. The 
counter output is a 440Hz square wave. 

You may know that a square wave can be represented as the sum of many 
sine waves. The frequency of the second and all following sines in this sum are 
integer multiples of the first whose frequency matches that of the square wave. 
Each sine wave has an associated amplitude which determines its contribution 
to the final sum. Mathematicians call this representation a Fourier series. 

Removing the higher frequency sine waves and sending what is left to a 
speaker produces music. On the PC, the filter removes the high-frequency 
sound waves. Technically, this filter is called a low-pass filter because it allows the 
low-frequency waves to pass and stops the higher-frequency ones. 

Changing the divisor while the speaker is on results in an unpleasant tone. 
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Clock in 


Speaker 
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Fig. 11-6. Sound generation hardware. 


The speaker can be turned on and off under software control. Whenever we want 
to change the sound frequency or produce a period of silence, we must turn off the 
speaker. This listing illustrates use of the sound generation hardware. 


INCLUDE HARDWARE. DEF ; SOUND driver hardware def'ns 


m1 = (SelCtr2 SHL SC) ; select counter 
_m2 = CLSBMSB SHL RL) ; select read/load 
_m3 = (Mode3 SHL M) ; select mode 
cntrlW EQU _m1 OR _m2 OR _m3 ; 8253 control word 


_text SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME CS:_text,DS:_text 


ORG 100H 
a440 PROC NEAR 
mov al,cntrlwW 3; Set up 8253 to function 
out 18253 .Mode, al ; as a tone generator 
call TurnOff s Turn off speaker 
mov ax,2712 ¢ ax <== frequency divisor 
out 18253.Ctr2,al ; Write LSB of divisor 
jmp SHORT $+2 : Delay for AT 
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xchg al,ah al <== MSB divisor 


e 
out 18253.Ctr2,al : Write MSB of divisor 
call TurnOn ; Turn speaker on now 
xor CX,CX ; Delay for a while 
xs Loop x ; (Period depends on CPU speed) 
call TurnOf f : Turn speaker off 
mov ah,4cH 3; Return to DOS 
int 21H 
a440 ENDP 
Speaker PROC NEAR 
out 18255.PortB,al ; Update 8255 
ret : and return 
TurnOff LABEL NEAR : Turn off speaker 
in al,18255.PortB ; Read current port settings 
and al, SpeakerOff ; Turn off the speaker 
jmp SHORT Speaker : Update 8255 (jmp req'd for AT) 
TurnOn LABEL NEAR s Turn on speaker 
in al,18255.PortB ; Read current port settings 
or al,SpeakerOn ; Enable the speaker 
jmp SHORT Speaker : Update 8255 (jmp req'd for AT) 
Speaker ENDP 
_text ENDS 
END a440 
System Clock 


The programmable interval timer chip (8253) actually contains three independ- 
ent down counters. One of these counters (Counter 2) is part of the sound gener- 
ation hardware and another (Counter 0) drives the system clock. DOS sets up 
Counter 0 the same as I programmed Counter 2 in the previous example. DOS 
uses a frequency divisor of 65536. (This value is actually loaded into the counter 
as 0. The 8253 decrements the counter first and then tests for 0.) The output of 
the counter, a 1.139180MHz/65536Hz (~ 18.2) square wave, is connected to chan- 
nel 0 (IRQ 0) of the 8259 interrupt controller chip. DOS programs the 8259 so 
that Counter 0 generates an interrupt 18.2 times a second. 


Overview of the SOUND Driver 


Now that we’ve reviewed driver basics and looked at the hardware used by our 
SOUND driver, let's see how the driver is implemented. There are three distinct 
parts to the SOUND driver—a DOS interface, a compiler, and a player. The DOS 
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interface is similar to the previously discussed prototype. The compiler and 
player expand this prototype to a fully functional character driver. 


DOS Interface 


The DOS interface consists of the device header, strategy entry, and interrupt 
entry. The attributes word of the device header DHD_W_Attrib declares the 
SOUND driver to be a character driver which supports WriteUntilBusy, IOCTL, 
and OCRM requests. The strategy code records the address of the request 
header. The interrupt code saves all registers, switches to an internal stack, and 
dispatches on request header function to a specific subroutine which completes 
the request. The driver saves information on its private stack between calls. Be- 
fore returning to DOS, the interrupt code switches back to the DOS stack, re- 
stores all processor registers, and sets a completion status in the request header. 


Compiler 


The interrupt entry code calls the SOUND driver output routines (SoundWrite and 
SoundWriteTilBusy), which pass characters from a buffer in the DOS request 
header to the compiler. The compiler converts ASCII text to note pitch and dura- 
tion information and stores the compiled data in a circular buffer. The compiler 
encodes pitch as an 8253 programmable interval timer frequency divisor and dura- 
tion as ticks of the system clock. A finite state machine implements the compiler. 


Player 


The player is driven by interrupts from the system clock. It removes compiled 
notes from the circular buffer and manipulates the PC sound generation hard- 
ware to produce music. The player loads pitch information into the 8253 Pro- 
grammable Interval Timer and initializes a counter with duration information. 
This counter is decremented on every tick of the system clock. When the tick 
count goes to zero, the player gets another note from the circular buffer. 


SOUND Driver Finite State Machine 
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There are three parts to the SOUND driver finite state machine: macros which 
describe the translation rules or grammar, subroutines which recognize spe- 
cific musical constructs, and an interpreter. The FSM. DEF include file defines all 
macros and internal data structures which the finite state machine uses; you 
will find a listing of this file at the end of the chapter. 
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Macros 


STATE and TRAN macros specify the rules for music compilation. The STATE 
macro identifies the start of a particular state, and the TRAN macro defines legal 
transitions out of this state. One or more TRAN macros follow each STATE macro. 
These two macros build the state transition table which drives the interpreter. 
The only argument for the STATE macro is a state name. The TRAN macro 
has four arguments: class, data, nstate, and action. Class is the name of a subrou- 
tine which recognizes a particular token such as a note or key signature. Certain 
class routines use the data argument. Nstate specifies the state which will be en- 
tered if a transition is successful. If the nstate argument is omitted, a default value 
of the next state in the transition table is used. Action is the address of an action 
routine, which can contribute to the decision of whether or not to accept a transi- 
tion or perform some special processing if a transition is successful. Action rou- 
tines are a hook for decisions that cannot be described easily by the state table. 


Class Routines 


Class routines assemble and examine tokens and they decide whether or not to 
make a transition. The class routines referenced in the TRAN macro are specific 
to music compilation. Every class routine returns with an unprocessed charac- 
ter in the AL register. 

Class routines recognize notes which include a name (A . . . G) and possi- 
bly an accidental, numbers, key signatures, and commands. The command rou- 
tine compares the current input character to the value in the data field; it is 
normally used in conjunction with the SubState class routine. 

SubState is a special class routine which saves the current state and enters 
the state specified by nstate—you can think of it as a subroutine call. SubState is 
used when a transition must be described in terms of other transitions. A transi- 
tion to $_exit causes a successful exit from SubState, a transition to S_fail 
causes an unsuccessful exit from SubState. The following example shows the 
state table entry which defines the Tempo command. This definition says that 
tempo is defined by the letter T, followed by a number. Notice how the Command 
class routine recognizes the letter T. If the current letter is not a T, the substate, 
s_t, returns a failure; otherwise, the Number class routine looks for a number. If 
a number is found, the TempoDone routine is called and a successful exit is 
taken from the substate s_t. 


state st 


tran Command, 'T’ 
state 
tran Number, ,S_exit, TempoDone 
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Interpreter 


The state machine interpreter keeps track of the current state, which is no more 
than a list of legal transitions. The interpreter passes the current character to 
each class routine which may need more characters to complete a token. At 
some point, the class routine will either recognize the token or return with a 
failure status. If the class routine returns success, the interpreter calls the op- 
tional action routine (if present). If this routine does not reject the transition, the 
interpreter enters the state specified by the nstate argument. A failure status 
causes the interpreter to process the next transition (if there is another one). 


SOUND Driver Coroutines 


The finite state machine analyzes characters which come from either Sound- 
Write or SoundWriteTilBusy requests. SoundWrite requests are one character 
long unless the SOUND driver is in binary mode. Binary mode and write-until- 
busy requests are arbitrarily long. 

Coroutines simplify the relationship between multiple entry points and the 
finite state machine. The finite state machine calls NextCharacter when it needs 
another character. In an effort to satisfy this request, NextCharacter makes a 
coroutine callback to the original driver entry point. The target of this callback is 
a loop within either SoundWrite or SoundWriteTilBusy. The loop logic removes a 
single character from the buffer specified in the request header and makes a 
coroutine callback to NextCharacter. If the current request header cannot pro- 
vide another character, the SOUND driver returns to DOS. Information saved on 
the driver-private stack ensures that processing will be resumed properly on the 
next driver call. Initialization code in the ResetExit routine sets up the initial call; 
normal coroutine processing propagates the calls. 


Synchronization and Circular Buffers 
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All circular buffer operations occur in BufferInsert and BufferRemove. Class 
routines call BufferInsert whenever a note or a rest has been completed. The 
player calls BufferRemove from the timer interrupt service routine when it is 
time to play another note. Neither of these operations is indivisible. Both rou- 
tines manipulate a common data structure which must be kept in a consistent 
State. 

The SOUND driver architecture makes synchronization between compiler 
and player easy. The player manipulates the next available note pointer, and the 
compiler handles the next free space pointer. Access to these pointers is com- 
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pletely independent and does not require synchronization. Both routines make 
indivisible adjustments to the buffer count. The increment operation used by 
the compiler and the decrement option used by the player are guaranteed to 
complete once started. 


Speeding up the System Clock 


We have tacitly assumed that DOS would provide clock ticks for the SOUND 
driver. It turns out that the system clock does not provide sufficient resolution. 
At the standard clock rate of 18.2 ticks per second, a quarter-note played at the 
default tempo of 120 lasts nine ticks (60 + 120 * 18.2). An eighth-note (half as 
long as a quarter-note) would last only five ticks. Since we need short periods of 
silence between notes, we actually would play an eighth-note as four audible 
ticks followed by one tick of silence. Because the tick per note is so small, we 
cannot accurately deal with tempo or the relative durations of short notes. The 
faster the tempo, the worse the problem becomes. 

An obvious solution is to increase the system clock speed, but this ap- 
proach might cause the processor to spend excessive time servicing timer inter- 
rupts. Since the ability to speed up the system clock was important, I created a 
prototype interrupt service routine. By the time I wrote this prototype code, I 
had designed all the driver data structures and decided how to implement the 
compiler; the interrupt service routine interface was completely specified. Using 
a factor of 16 speedup, I analyzed the time required to execute this prototype 
code. It was apparent from this analysis that I could safely increase the fre- 
quency of the system clock. 

Space constraints prevent a discussion of the prototype code, but it was 
almost identical to the code finally used in the SOUND driver. The estimate was 
so accurate because it was made after the interrupt service routine interface 
was completely specified. 


New Clock Interrupt Service Routine 


The following example illustrates the interrupt service routine code, which has 
some subtle aspects. We cannot just change the frequency of the system clock. 
On every clock tick, the clock interrupt service routine in ROM gets called. This 
code updates the time of day, checks the status of the diskette timers, issues an 
INT 1CH, sends an E01 to the 8259 interrupt controller, and dismisses the clock 
interrupt with an IRET. If the ROM BIOS routine were called too frequently, the 
system clock would gain time and diskette operation would be impaired. Any 
other device driver or TSR program which linked to the INT 1CH vector would 
also be called too often. It is difficult to predict the effects of more frequent calls 
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to these linked routines, but a significant percent of the available CPU cycles 
could be spent servicing the timer interrupt and traversing the INT 1CH chain. 


CLkKISRO: 
cmp cs:NoteTicks,O ;;; CABC(22)]Playing a note? 
jz clkO 327 CABC(16/4]1f Z--no 
dec cs:NoteTicks s2; (BC(31)]Decrement note count 
jnz clkO tz; (BC(16/5)]If NZ not note end 
call PlayNextNote 27 (C(€23+496)]Play another note 
clkO: dec cs:ClockTicks 73; CABC(31)]Dec clock ticks 
jz clk3 7773 CABC(16/4)INot time for old 
333 clock isr 
ClkIntExit: 
push ax s33 CABC(15)]Save ax 
mov al ,E0! 773 [CABC(4)]Send Nonspecific EOI 
out 18259.PortA,al 33; CABC(10) JEOI to 8259 
pop ax 33 CABC(12)]Restore ax 
iret 373 CABC(32)Jand exit ISR 
clk3: css 333 (22)Reset counter 
mov ClockTicks, FastTickCount 
cs: 33 (32) Call old clock isr 
jmp OldInt8Vector 
CLKISR1: 
cmp cs:ClockTicks,1 33; Can clock frequency change? 
jl clk2 77 If L--no reset ClockTicks 
ig clk1 333 If G--not yet 
call SetClockSlow sz: Enter slow mode 
cs: 333 Say not busy 
and DriverStatus,NOT MASK Busy 
clk1: dec cs:ClockTicks 33; One more tick 
jmp SHORT CLkIntExit;;; and exit ISR 
clke: cs: 33; Set ticks to wait 
mov ClockTicks,FastTickCount 
jmp SHORT ClkIntExit;;; and exit ISR 
SetALtISR: 
and DriverStatus,NOT MASK EOFPending ;3; EOF not 
iz pending 
or DriverStatus, (1 SHL ChangePending) 33; but vector 
333 change is 
mov ax, OFFSET CLKISR1 333 Played last note 
call SetISR 332 Swap clock ISR 
ret 333. and return 
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When we change the frequency of the system clock, we must also change 
the clock interrupt service routine. Changing the clock frequency is easy. We 
change the frequency divisor from 65536 to 16384 (0x1000) to get a factor of 16 
speedup. We also must change the clock interrupt vector to point to the new 
clock interrupt service routine. 

The first action performed by the CIkOISR code is to check the value of 
NoteTicks. If a note is currently being played, NoteTicks will be nonzero. Only 
nonzero values are decremented. When NoteTicks becomes zero, it is time to 
play a new note. Whether any note processing took place or not, ClockTicks is 
decremented. When this value becomes zero, it is reset to 16 (the clock speedup 
factor), and the old INT 8 service routine is invoked with a JMP instruction. 

Invoking the old INT 8 routine every 16th-fast clock tick maintains the 
proper delay between calls. The transfer of control is done with a JMP instruc- 
tion to ensure that only one EOI gets sent to the 8259 interrupt controller. (Re- 
member, the ROM BIOS interrupt service routine wants to send an E01.) 


Driver Performance 


Estimating driver performance is done by calculating execution times for worst 
case code paths. These estimates provided assurance that DOS could handle the 
clock speedup and that the driver could play notes in real time. At the faster 
clock rate, there are 3432800 ns (nanoseconds) between interrupts (1193180 + 
4096 = 291interrupts/sec = .0034328 sec/interrupt = 3432800 ns/interrupt). 

In the previous example of the clock interrupt service routine, the num- 
bers in parentheses are instruction times in clock cycles and the letters inside 
square brackets are code paths. 

When no note is playing and the BIOS interrupt service routine does not 
need to be invoked, code path A is followed. This path takes 197 clock cycles (51 
+ 22 + 16+ 314+ 4+ 15+ 4+ 10 + 12 + 32). The PCrunsata clock speed 
of 210 ns; this path requires 41370 (210 x 197) ns or 1.2 percent (41370 + 
3432800 x 100) of the available CPU cycles (to a first approximation). 

When a note is playing and the ROM BIOS interrupt service routine is not 
called, code path B is followed. The processor overhead for this path is 1.4 per- 
cent. When a new note has to be played (path C), overhead goes up to 4.5 per- 
cent. No estimates were made on how much time was required to execute the 
original BIOS interrupt service code or compile the text. The number of routines 
chaining to the 1CH interrupt is unpredictable and can have a drastic effect on 
the length of this code path. So long as this path takes less than 6 percent (100 x 
41s) of the total CPU cycles, we should not miss any “fast ticks.” 

A significant portion of the time available for compile is spent in DOS code. 
If we make a worst case assumption that BIOS code and resident timer routines 
take up 6 percent of the CPU cycles and that playing a note takes up 4.0 percent 
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(certainly a very conservative assumption since notes are changed relatively in- 
frequently), we still have 90 percent of the processor cycles available. There 
should be no problems playing most scores in real time. When the completed 
driver was tested by copying a score to it, it was found that the copy command 
completed before the music stopped confirming this analysis. Isn't all this sci- 
ence wonderful! 


Adding Refinements 
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The system clock can be permanently sped up by changing the counter fre- 
quency and interrupt vector in the SOUND initialization routine (SoundInit), or 
the clock frequency can be altered when music is being played. The former ap- 
proach would work at the expense of some wasted CPU cycles when the SOUND 
driver is not being used, but, as our performance analysis shows, its impact 
should not be noticed. The SOUND driver uses the latter technique. This ap- 
proach is more elegant and provides further examples of driver synchroniza- 
tion as well as illustrating nonstandard uses for open and close routines. The 
system clock is sped up in the open routine and slowed down in the close rou- 
tine. 

The OCRM bit is set in the device header. When the device is closed either 
explicitly or implicitly by process termination, DOS sends a close request to the 
SOUND driver. The Interrupt code dispatches to the SoundClose routine which 
informs the state machine that a close operation has been requested (an EOF is 
passed through the NextCharacter coroutine). With interrupts disabled, the 
driver state is set to end of file pending and NoteTicks is tested. It is important 
that both actions are taken with interrupts disabled. Note playing is interrupt 
driven and will always take precedence over compiling. If NoteTicks ever goes to 
0, the compiler is sure that the Player has nothing to do. If the Player has nothing 
to do and a close has been sent to the driver, SoundClose resets the clock speed 
to slow and restores the original interrupt service routine (call SetAItISR). If 
NoteTicks is nonzero, the Player is currently busy. Eventually the Player will run 
out of notes, notice that a close has been requested (driver state will be end-of- 
file pending), and reset the clock speed and interrupt service routine. 

If interrupts are not disabled while the driver state is changed and Note- 
Ticks is checked, an interrupt could occur between the two instructions. If the 
final note completed between these two instructions, SetAltISR would be in- 
voked twice. If the order of these two instructions were reversed, SetAltISR 
might never get called. It is important that the two instructions be executed 
without interruption. The CLI instruction ensures that this critical section com- 
pletes without interruption. 

The actual swap of interrupt vectors is slightly more involved than what 
has been previously described. We want to change vectors and slow down the 
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clock on the 16th-fast tick so we do not lose any time (on the average 25 ms per 
close). To avoid time loss, SetAltISR sets the driver state to change pending and 
changes the interrupt service routine to ClkISR1. CIkISR1 waits for the Clock- 
Ticks to go to one, then slows down the clock and restores the interrupt vector 
to its original value. 

Since the OCRM is set in the device header, the SOUND driver is called each 
time the device is opened. The SoundOpen routine processes open requests. It 
immediately clears the end of file pending driver state. If a vector change is 
pending, a busy wait loop is entered. SoundOpen could back out of the vector 
change, but very little would be gained and the code complexity would increase. 
If two songs are played in quick succession, it is possible that the interrupt vec- 
tors will not change and the clock speed will not be altered between songs. 
Whenever the vector and clock speed are in their original state, the driver state 
is InitNeeded. If SoundOpen finds the driver in the InitNeeded state, it changes 
the interrupt vector to CIkOISR and speeds up the clock. 


Finishing Touches 


The open routine (SoundOpen) speeds up the clock and copies the 
CErr.ERR_L_Bytes and CErr.ERR_A_Text values. These variables describe the last 
error and identify where it occurred. SoundOpen then resets the error descrip- 
tion and initializes some driver parameters. It also initializes the driver stack and 
calls ResetExit to set up the initial coroutine callback. 

The SOUND driver supports both input and output IOCTL routines. These 
routines allow the user to read or modify the default tempo, octave, and style. 
They also allow the user to interrogate the driver about the most recent com- 
piler errors. Error information is read-only. 

As I mentioned previously, the driver is free to interpret the IOCTL infor- 
mation as it sees fit. The SOUND driver expects to be passed a list of requests. 
Each list element has a request identifier, request length, buffer address, and a 
return length address. Both addresses are specified with a segment and an off- 
set. The optional return length address is the address of a variable which will be 
set to the actual number of bytes returned. The following listing requests the 
current default note length, octave, and the text of the last compiler error. 


ITEM STRUC 

ITEM_W_Code DW 0 ; Request code 

ITEM_W_Length OW 0 ; Allocated size 

ITEM_A_Address OW 0 ; Address of item buffer 
DW 0 

ITEM_A_RetLen DW 0 ; Address of actual length 
DW 0 ; Cignored if segment=0) 
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ITEM 


IOCTL_K_CBytes 
IOCTL_K_PBytes 
IOCTL_K_CError 
IOCTL_K_PError 
IOCTL_K_Length 
IOCTL_K_Octave 
IOCTL_K_Tempo 

TOCTL_K_Style 


stack SEGMENT 
DW 
stack ENDS 


_data SEGMENT 


sound DB 
itmlst ITEM 
ITEM 


me =e 7) 


ITEM 


itmend EQU 
Length OW 
Octave OW 
TLength DW 
Text DB 
_data ENDS 


_text SEGMENT 
ASSUME 
main PROC 
mov 
mov 
mov 
mov 
int 
mov 
mov 
mov 
mov 
int 


ENDS 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


mea ee =e @e ee Se Me ME 


No uu & WN | © 


WORD STACK ‘STACK’ 
256 DUP(O) 


WORD PUBLIC ‘DATA' 
‘SOUND’ ,O 


Get 
Get 
Get 
Get 
Get/Set 
Get/Set 
Get/Set 
Get/Set 


current 


bytes read 


previous bytes read 


text of 
text of 
default 
default 
default 
default 


current error msg 
previous error msg 
note length 

octave 

tempo 

style 


<IOCTL_K_Length, 2,OFFSET Length,SEG _data,0,0> 
<IOCTL_K_Octave, 2,OFFSET Octave,SEG _data,0,0> 


<IOCTL_K_CError,50,OFFSET Text, 
OFFSET TLength,SEG _data> 


ooo # 


50 DUP(O) 


BYTE PUBLIC ‘CODE’ 
cs:_text,ds: data 
NEAR 

ax,_data H 
ds,ax 

dx,OFFSET sound 
ax ,3d01H 

2th 

bx, ax H 
dx,OFFSET itmlst; 
cx, itmend-itmlst; 
ax, 4402H : 
21H 


Note that you cannot actually wrap structure reference 


SEG _data, 


Return default length here 
Return default octave here 
Length of Text 

Error text here 


Establish data segment 


Open device (need handle) 
Say write-only access 


bx <== handle 


dx <== jtem list 


cx <== length of item List 
issue a read IOCTL 
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mov ah,4cH ; Return to dos 
int 21H 

main ENDP 

_text ENDS 
END main 


Coroutines are also used to implement the list processing. The read or 
write IOCTL routines call FirstItem to process the first IOCTL item; coroutines 
satisfy the remaining requests. 


Conclusion 


In this essay, I have introduced some new programming techniques and shown 
how they are used in a real device driver. A listing of this driver and its include 
files appears next. The techniques I have described and much of the code is di- 
rectly applicable to other drivers. 

To write your own device driver, you will need to understand the hardware 
you are controlling. Most purchased hardware comes with a technical descrip- 
tion similar to what is provided in the IBM Hardware Technical Reference Manual. 
Usually, this description does not include sufficient information to write a device 
driver, and you will have to consult the component data catalogs provided by 
chip vendors. These catalogs usually contain a complete description of how a 
chip works and many also provide sample circuits and code. 

Listing 11-1 gives the complete source listings for the SOUND driver. The 
main program PLAY .ASMis followed by its supporting include files, which are pre- 
sented in the order they appear in the INCLUDE statements. This listing is thor- 
oughly commented. 


Listing 11-1. Sound Driver 
a 


° 
e 


TITLE SoundODriver 
SUBTTL Basica 3.0 Compatible Sound Driver 


SOUND.ASM 


Source for SOUND device driver 


© 1987 W. V. Dixon. ALL rights reserved. 
continued 
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May be freely copied for personal, nonprofit use 


; so long as this copyright notice and disclaimer are 

; retained and usage restrictions are observed. This 

; software may not be used in whole or in part in any 

; program which is sold without prior written consent 

; of the author. 

i 

: 

; DISCLAIMER 

Ps s<sSsosscscssscs 

; 

; This software is furnished as an example of a character 
; device driver. The author will assume no responsibility 
; for any direct or indirect damages resulting from the use 
; of this code. You are using this software ENTIRELY AT 

; YOUR OWN RISK. 


INCLUDE MACROS.ASM s Useful macros 

INCLUDE DEVICE.DEF 3 Device driver data structures 
INCLUDE VALUES.DEF ; Limits and parameters 

INCLUDE HARDWARE .DEF ; PC hardware definitions 

INCLUDE FSM.DEF 3; Finite state machine definitions 


SUBTTL Driver-specific macro definitions 


PAGE 
; 
; Macro to associate text with message number. The message 
; number is defined as the address of the text string. 


error_msg MACRO number,text 


LOCAL x 
LOCAL y 
x DB y7x-1, text ,0 33 Define message text 
y: 
number EQU OFFSET x :: Define error number 
ENDM 3; MACRO error_msg 


continued 
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; Signal that an error occurred. 
? 
signal MACRO x 
mov CX,X 77 CX <== error number 
jmp WriteFaultExit 3; and take error exit 
ENDM ;; MACRO signal 
; 
: Define a musical scale 
' 
defscale MACRO name,scale,sharps, flats 
name: DB scale 7; Specify notes in scale 
IRPC y, <sharps> 33 Specify which notes are sharp 
DB &y 
ENDM 77 IRPC sharps 
IRPC y,<flats> :3 Specify which notes are flats 
DB &y 
ENOM 7; IRPC flats 
ENOM 3; MACRO defscale 
SUBTTL Data Structures 
PAGE 
; 
; Define driver status summary word 
; 
DSS record InitNeeded:1,Busy:1,ChangePending:1,E0FPending:1,InComment:1, 
InTie:1,HasNote:1 
DSS_M_HasNote EQU 1 SHL HasNote ; Compiler has note 
DSS_M_InTie EQU 1 SHL InTie ; Compiler processing tie 
DSS_M_InComment EQU 1 SHL InComment ; Compiler processing comment 
DSS_M_EOFPending EQU 1 SHL EOFPending ; End file pending 
DSS_M_ChangePending EQU 1 SHL ChangePending ; Vector change pending 
DSS_M_Busy EQU 1 SHL Busy ; Device is in use 
DSS_M_InitNeeded EQU 1 SHL InitNeeded ; Clock speedup needed 


Define Score (SCR) structure 


=e =e fe 


SCR STRUC 
SCR_W_Length DW SCR_K_DLength ; Note length 
continued 


387 


Section 3: Working with the Hardware Interface 


SCR_W_Octave OW 
SCR_W_Tempo DW 
SCR_W_Key DW 
SCR_W_Style DW 
SCR_W_Ticks OW 
SCR_W_TTicks DW 
SCR_W_TFreq DW 
SCR_W_NTicks DW 
SCR_W_NFreq DW 
SCR ENDS 
SCR_S_Size EQU 


=e ome =e 


ERR STRUC 
ERR_L_Bytes OW 0,0 4 
ERR_A_Text DW 0 : 
’ 

ERR ENDS 
ERR_S_Size EQuU SIZE ERR 
? 
7 Define IOCTL item list structure. List is 
. elements. 
; 
ITEM STRUC 
ITEM_W_Code OW 0 
ITEM_W_Length DW 0 
ITEM_A_Address DD 0 
ITEM_A_RetLen DD 0 
ITEM ENDS 
ITEM_S Size EQU SIZE ITEM 

SUBTTL Constant Definition 

PAGE 
: 
; Miscellaneous ASCII symbols 
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SCR_K_DOctave 
SCR_K_OTempo 
0 


SCR_K_DStyle 
SCR_K_DTicks 


0 

0 
SCR_K_DTicks 
0 

SIZE SCR 


Define Error structure 


we Se ™8 we MO 


=e ee ese Be we 


Octave 

Tempo 

Key signature 

NB Must fill in when defined 
Style 

Current tick count 

Tied tick count 

Tied frequency divisor 

Note ticks 

Note frequency divisor 


Bytes read 
Address of error text 
NB Must fill in when defined 


array of ITEM 


s Request code 


s Allocated size 

3; Address of item buffer 

: Address of actual length 
: Cignored if segment=0) 


continued 
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IOCTL_K_CBytes 
IOCTL_K_PBytes 
IOCTL_K_CError 
IOCTL_K_PError 
IOCTL_K_Length 
IOCTL_K_Octave 
IOCTL_K_Tempo 

IOCTL_K_Style 


=e se me 


_temp_ 
_temp_ 
DHO_C_Attrib 


IVTSegment 


Int8Vector 
IVTSegment 


_text 


EQU 
EQU 
EQU 
EQU 


EQUu 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


Driver attributes 


EQU 


SUBTTL IVT Definition 


PAGE 


SEGMENT AT 0 
8 DUP(O) 


DD 
DD 
ENDS 


SUBTTL Driver Data Declarations 


PAGE 


ORG 


07H 
OaH 
QdH 
1aH 


Item codes for IOCTL requests 


NO WwW fF WN = © 


Driver parameters 


word 
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Used to tell state machine 


about end 


Get 
Get 
Get 
Get 
Get/Set 
Get/Set 
Get/Set 
Get/Set 


=e w~e Be we Bele lO 


of file 


current bytes read 
previous bytes read 

text of current error msg 
text of previous error msg 
default note length 
default octave 

default tempo 

default style 


DHD_M_IsCharacter OR DHD_M_IOCTLSupport 


_temp_ 
_temp_ 


0 


SEGMENT BYTE PUBLIC ‘CODE’ 
ASSUME cs:_text,ds:_text 


OOH 


. 
e 
e 
a 
° 
e 


OR DHD_M_WriteBusySupport 
OR DHD_M_OCRMSupport 


To reference interrupt vectors 
Don't care about these 
Timer (8253 Counter 0) interrupt 


continued 
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driver PROC NEAR 


Declare device header 


=e =e me 


begin: DHD <-1,DHD_C_Attrib, StgyEntry, IntEntry,'SOUND ‘> 


Driver action table used to dispatch to appropriate processing routine 
; based on request type. 


RQ_T_Tabl DW SoundInit ; Device Initialization 
DW SoundNOP s Media check 
DW SoundNoP s Build BIOS parameter block is 
DW SoundInIOCTL s Input IOCTL request 
DW SoundError 3: Input (read) request 
DW SoundError 3; Nondestructive input 
DW SoundError ; Input status 
DW SoundError : Input Flush 
DW SoundWrite ; Output (write) 
DW SoundWrite ; Output write with verify 
DW SoundStatus ; Output status 
DW SoundF lush s Output flush 
DW SoundOut IOCTL ¢ Output IOCTL request 
DW SoundOpen s; Device open request 
DW SoundC lose ; Device close request 
DW SoundNOP 3 Removable media 
DW SoundWriteTi lBusy : Write until busy 
RQ_S_Table EQU ($-RQ_T_Table)/2 
; 
: Table used for processing IOCTL requests 
; 
: Address Length 
; pan bart — tt — 4 sss 
: 
IOCTL_T_Table OW CErr.ERR_L_Bytes, 4 
DW PErr.ERR_L_Bytes, 4 
DW CErr.ERR_A_Text, 0 
DW PErr.ERR_A_Text, 0 
DW DScore.SCR_W_Length,2 
DW DScore.SCR_W Octave,2 
continued 
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DW DScore.SCR_W_Tempo, 2 
DW DScore.SCR_W Style, 2 
IOCTL_S_Table EQU ($-IOCTL_T_Table)/4 


State table. Defines state transitions for device driver state 
machine. 


=e =e & ee fe 


state s_main 
tran lambda, , ,CompileNote 
state 


This is the main state 
Compile note (if completed) 


ue me 


tran substate,s_note,s_main Note 
tran substate,s_l,s_main Length (Lnn) 
tran substate,s_p,S_main Rest 


Octave (On) 

Numeric note (Nnn) 

Tempo (Tnnn) 

Key signature 

Music style (ML, MN, MS) 
Gracefully terminate state machine 


tran substate,s_0,S_main 
tran substate,s_n,s_main 
tran substate,s_t,S_main 
tran substate,s_key,s_main 
tran substate,s_music,s_ main 
tran Command, EOF,s_main 


=e me =e =e me =e =e me me “=e ame me 


state sl Process length 

tran Command, 'L' Need 'L’ first 

state ‘L' must be followed by 
tran DottedNumber,,s_exit,LengthDone : dotted number 
state st Process tempo 

tran Command, 'T' Need ‘T’ first 

state ‘T’ must be followed by 


tran Number,,s_exit, TempoDone number 


state sin Process numeric note 
tran Command, 'N' Must begin with ‘N' 
state 'N’ must be followed by 
tran Number, ,S_exit,NoteDoneD a number 

state so Process octave 


tran Command, '0' 

state 

tran Number, ,S_exit,OctaveDone 
state s_key 

tran Command, 'K' 


Must begin with ‘0’ 

‘O' must be followed by 
a number 

Process key signature 
Must begin with ‘K' 


=e 99 =e 5S we S80 we M8 lM elUOUlUOlUlU lO =e 


state ; ‘K’ must be followed by 

tran Signature, ,s_exit,SignatureDone ; a valid signature 

state  s_music 3; Process music command 

tran style,,s_exit,StyleDone ; Must be a valid style 

state s_p ; Process a pause (rest) 
continued 
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tran Command, 'P' ,np_length, PauseDone 3; Must begin witn 'P' 
state s_note ; Process a note 
tran Note, ,np_length,NoteDone1 s Must begin with valid note 
state np_length 3 Length of note or rest 
tran Dots,,S_tie,NPDoneO : Dots may follow 
tran DottedNumber, ,s_tie,NPDone1 ; Dotted number may follow 
tran lambda, ,s_tie,NPDone2 : Anything else ends note 
state s_tie ; Look for ties 
tran Command, '&',s_exit, TieDoned ; '&' starts a tied note 
tran Lambda, ,S_exit, TieDone1 3 Anything else ends note 
state_end ; End of driver state table 

: 

: Style table is used to define various music styles. These styles are 

: indicated by MN (Normal), ML (Legato), and MS (Staccato). 

; 

StyleTable 0B 'MNLS' ,StyleStaccato, StyleLegato,StyleNormal 


=e me =e =e me =e =e =e me =e 


=e 


defscale 
defscale 
defscale 
defscale 
defscale 
defscale 
defscale 
defscale 
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Key Scale Sharps 


Define scales for each key signature. There are 12 positions in 
each scale beginning with C flat (C-) and extending to B sharp (B+). 
The position of the note name indicates whether it is sharped or 
flatted in the key signature in question. (Note that the notes of 
the scale are in reverse order so we can conveniently use a scab 
instruction. The scale column is used to determine a notes pitch. 
The sharps and flats column also tell whether the note is normally 
sharped or flatted; they are used in processing accidentals. 


Flats 


H=#=H=H==H=H=H «=HBHAHGAFEADACH ABRARGHFEADACH 


omprReoao 
*. 


BAG FE DC ",01010101101010,01010101101010 
," BA GF E DC *,01010100101010,01010102101010 
." B AGF E DC ",01010100101000,01010102101020 
BAG FE oc ™,01010000101000,01010202101020 
," BAG F EDC ",01010000100000 ,01010202102020 
." BAG F EDC ",01000000100000 ,01020202102020 


FSharp," BA G FE DC ™,01000000000000 ,01020202202020 
CSharp,"B AG FE DC ",00000000000000,02020202202020 
ea-s-s-ss-s-= -B-A-G-FE-D-C- -B-A-G-FE-D-C- 


continued 


defscale 
defscale 
defscale 


Chapter 11: A SOUND Device Driver 


F e'' BA G FE D C ",02010101101010,00010101101010 
BFlat ," BA G F ED C ",02010101201010,00010101001010 
EFlat ," BAG F ED C ',02020101201010,00000101001010 


defscale AFlat ," B AG F E DC ",02020101202010,00000101000010 


defscale 
defscale 
defscale 


. Define the key si 
: the previous scal 
: convenience in us 


Keys DB ' 


DOFlat ," BA GF E DC ",02020201202010 ,00000001000010 
GFlat ," BA GF E D Ct,02020201202020 ,00000001000000 
CFlat ,“ BAG FE D C',02020202202020 ,cOC00000000000 


gnatures. The order in this table corresponds to 
e definitions. Again we reverse the order for 
ing the scasw instruction. 


C-G-D-A-E-B-F C+F+B EADGC ' 3; note reverse order 


: The following table defines the counter (8253 counter 3) value for each 


: note. Values are 
: (1193180) by the 


; C 


calculated by dividing the input oscillator frequency 
note pitch (in Hz). 


C# D D# E F FH G G# A 


A# B 


FreqDivTable DW 36156, 34090 , 32248 ,30594, 29101, 27117, 25386, 24350, 22945, 21694, 20572,19244 
DW 18356, 17292, 16124,15297 ,14550,13714,12829,12175,11472,10847,10198, 9700 


DW 
DW 
DW 
DW 
DW 


9108, 8584, 8007, 7648, 7231, 6818, 6449, 6087, 5736, 5423, 
4554, 4307, 4058, 3836, 3615, 3418, 3224, 3043, 2875, 2711, 
2281, 2153, 2032, 1918, 1810, 1709, 1612, 1521, 1435, 1355, 
1140, 1075, 1015, 958, 904, 854, 806, 760, 718, 677, 
570, 538, 507, 479, 452, 427, 403, 380, 359, 338, 


; Associate message text with error number. The error number is actually 


. the address of th 


e text string defined in the following table. The 


: message text is returned in an OutputIOCTL request. 


error_msg 
error_msg 
error_msg 
error_msg 
error_msg 
error_msg 
error_msg 
error_msg 
error_msg 


BadStateTable, ‘Driver internal error: state table bad’ 
NumberTooLarge,'Number is too large’ 
BadSignature,'Key signature is bad’ 
BadLength,'Length is out of range’ 
BadOctave, ‘Octave is out of range’ 
BadTempo, ‘Tempo is out of range’ 
BadNote,'Note is out of range’ 
BadTie, ‘Tied notes must be the same’ 
Successful,'No errors encountered’ 
continued 


5120, 4830 
2560, 2415 
1280, 1207 
642, 603 
321, 301 
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LocalStack OW 256 DUP(O) ; Private stack for driver 
DriverSP DW $-2 ; Current top of stack 

DosSS DW 0 3; DOS stack segment on entry 
DossSP DW 0 ; BOS stack pointer on entry 
RqOffset DW 0 3 OFFSET of DOS i/o request 
RqSegment DW 0 ; SEGMENT of DOS i/o request 

H 

: Circular buffer for storing notes as they are compiled. Notes are 

.: put in at one end (BUF_A_NextFree) and removed from the other 

: (BUF_A_NextData). When the buffer is empty, BUF_W_Count=0, 

; 

BUF_T_Notes DD BUF_S_ Notes dup(0) ; Buffer for note duration and pitch 
BUF_W_Count OW 0 3; Notes currently in buffer 
BUF_A_NextFree DW BUF_T_Notes ; Next free buffer location 
BUF_A_NextData DW BUF_T_Notes ; Next data item in buffer 
OldInt8Vector DD 0 3; Original timer (8253) interrupt 
vector 

ClockTicks DW 0 ; Used to count clock ticks 
NoteTicks DW 0 ; Used to measure note duration 
PErr ERR <,Successful> : Previous error bytes and text 
CErr ERR <,Successful> ; Current error bytes and text 
CScore SCR <,,,5C€R_K_DKey> 3; Current values 

InitialCErr ERR <,Successful> ; Initial CErr values 

DScore SCR <,.,5CR_K_DKey> ; Default Values 


me me Me 


SavedCX OW 

SavedSI DW 

SavedDS OW 

DriverStatus DSS 
PAGE 

’ 

H WriteFaultExit 
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SUBTTL Driver Exit Routines 


10 request state information 


- Come here when want to return a 


Bytes left to read 
Buffer OFFSET 
Buffer SEGMENT 


Device driver status summary 


WriteFault error 
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e 


WriteFaultExit: mov ax, DHD_C_ErrWriteFault ; Say a write fault occurred 

; 

; ResetExit - Come here to reset driver state. Error code in ax. 

; 

ResetExit: mov sp,OFFSET DriverSP-2 ; Reset driver stack 
mov bx OFFSET StateMachine 3; To get to state machine 
push bx 
sub sp,6 ; For NextCharacter registers 
mov bx OFFSET nc4& s To set up initial coroutine 

dispatch 
push bx 
jmp SHORT DriverExit 3 and take common exit 

; 

; SuccessExit - Come here to return successful completion to DOS. 

; 

SuccessExit: mov ax,DHD_M_StsDone ; Say we were successful 

r 

: DriverExit - Common driver exit code. Returns error code and 

7 restores DOS state. 

’ 

DriverExit: les bx ,OWORD PTR RqOffset ; ES:BX <== DOS request 
mov es: [bx] .RH_W_Status, ax ; Return exit status to DOS 
mov DriverSP,SP ; Save driver stack 

; 


mov SS,DosS$ Restore dos stack 


mov SP,DosSP 


popf ; Restore flags 

pop_all : Restore all registers 
return_far ; and return to DOS 
PAGE 


SUBTTL Get Next Character (Coroutine) 


Called by state machine to read next character. The driver will have 
previously set up a coroutine call back (in BP). NextCharacter makes 
a coroutine callback to appropriate driver write routine. The write 
routine makes a call back to NextCharacter thus propagating the call 
back address. 


=e me =e me =e =as =e 


NextCharacter: pushr <bx,cx,di> ; Save nonvolatile registers 
jmp SHORT nc3 ; Skip special cases 
continued 
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ncQ: 


nei: 


nce: 


ne3: 
nc4: 


nce5: 


=e =e 68 


StateError: 
StateMachine: 


mainO: 


maint: 


maine: 


main3: 
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or 
jmp 
mov 
jmp 
and 
cmp 
j2 
call 
pop 
cmp 
jl 
test 
jnz 
cmp 
jz 
cmp 
jz 
job 
sub 
popr 
exit 


PAGE 


DriverStatus,DSS_M_InComment 
SHORT nc3 

al,'t! 

SHORT nc5 

DriverStatus,NOT MASK InComment 
al, EOF 

nc5 

bp 

bp 

al,’ ' 

nce2 

DriverStatus,MASK InComment 
nc3 

al,'!' 

ncO 

al, '#! 

nei 

al,‘a','2',nc5 

al,20h 

<di,cx,bx> 

success 


SUBTTL Driver State Machine 


signal 
mov 
push 
mov 
call 
jnc 
lea 
jmp 
test 
jz 
call 
je 
mov 


jmp 


Come here when state machine gets confused 


BadStateTable 

bx,-1 

bx 

bx, OFFSET s_main 
{bx].FSM_A_Class 
main2 

bx, [bx]. FSM_A_Ntrans 
SHORT mainO 

(bx) .FSM_A_Action,Offffh 
main3 

Cbx) .FSM_A_Action 
maini 

bx, [bx]. FSM_A_Nstate 


SHORT mainO 


continued 


=e =e =e me =e -me me =e 


=e 6=e 


CT ee) ee ee Se eT ee 


me me me =e ee we ue me =e =e me =e =e me me 


Say we're in a comment 

and get another character 

Change '#' to ‘+! 

and exit with ‘+t’ 

Say comment has ended 

Was it an EOF that ended it? 

If Z--yes (Exit with EOF) 

Return to coroutine for next char 


Is this a printing character? 
If L--nonprinting 

Are we in a comment? 

If NZ--we are 

Are we starting a comment? 

If Z--yes 

Is ths a '#'? 

If Z--yes (Convert to ‘'+') 

If not lowercase, exit directly 
Convert to uppercase 

Restore nonvolatile registers 
and return to caller 


Say the state table is bad 
Mark initial state 

and put on stack 

bx <== initial state 
Dispatch on class 
Transition successful 

Take next transition 

and dispatch on transition 
Any action routine? 

If Z2--no action routine 
and call action routine 
Action routine rejected transition 
Transition successful 
Move to next state 
and dispatch 


PAGE 


SUBTTL State Machine Class Processing 


me me me me me =e 


new, 
Classes PROC 
Substate: add 
push 
mov 
jmp 
Command: cmp 
jz 
exit 
sO: call 
exit 
Lambda: exit 
successful 


exit_failure: 


~e we Be fe 


NEAR 


sp,2 

bx 

bx, Cox] .FSM_W_Data 

mainO 

al,byte ptr (Cbx].FSM_W_Data 
sO 

failure 

NextCharacter 

success 

success 


stc 


State_exit: popr <si ,bx> 
pushf 
cmp bx, 71 
jnz seO 
mov si,OFFSET StateError 
se0: popf 
jmp si 
exit_success: cle 
jmp SHORT state_exit 
; 
; Process a string of one or more dots (.) 
; 
dQ: call NextCharacter 
d1: cmp al,‘.! 
loopz dO 


continued 
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Defines class processing action. BX has current state. Values are 
returned in CX. If class action is unsuccessful, 
causing failure is in AL. If the action is successful, 
unprocessed character. 


the character 
AL has a 


Remove return address 

Put current state on stack 

Get next state 

And return to state dispatcher 
Look for a character match 

If 2--found one 

No match--say we failed 

Get a new character 

and say match occurred 

Lambda transition always 


Say transition failed 


Common state transition exit. Restores state. Makes sure that stack 
is not messed up. Previous state is returned in BX. 


Recover state and return address 
Remember carry state 

Popped too many states? 

If NZ--we're still OK 

Force error exit 

Restore carry state 

Return to caller or StateError 
Say transition successful 

and take common exit 


Get next character 
Is character a dot? 
It is a dot. Get another character 
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neg cx ; Convert loop count to dot 

dec cx 3 count 

cle ; Assume successful 

or CX,CX ; Was there a dot? 

jnz d2 3; Must have at least 1 dot 

stc 3; Say we failed 
de: ret ; Return with status (success or 
failure) 
Dots: xor Cx,CX Initialize loop count 


jmp SHORT d1 Look at current character 


Convert an ascii number ‘0’ to '9' to a binary value. Return with 
cy=1 if not a number. 


=e =e =e =e 


bdO: exit failure : Say this isn't a digit 
BinaryDigit: job al,’0','9',bd0 
sub al, 'O' ; Ascii to binary conversion 
xor ah,ah ; Byte to word conversion 
mov CX, ax 7; cx <== converted digit 
ret ; and return to caller 
; 
: Process a number. Number is returned in CX. CY=1 if no digits found. 
: 
Number : call BinaryDigit ; Convert first digit 
je NoNumber : If c--no number 
push cx 3; Save number (first digit) 
ni: call NextCharacter 3; Get next character 
call BinaryDigit ; Convert to binary 
je NumberExit s; Not a digit--we are done 
mov ax,10 : Accumulate digit 
pop dx ; Old number 
mul dx 3 axsdx <== old number*10 
or dx , dx ¢ Product > 64K? 
jnz NumberError 3; If NZ--yes (too large) 
add Cx, ax 3; cx <== digit + 10*old number 
je NumberError 3; If c--number too large 
push cx : Save number 
jmp SHORT n1 : and get next digit 
NumberExit: pop cx 3 cx <== number 
exit success : Say we succeeded and return 
NumberError: signal NumberTooLarge ; Say number too Large 
NoNumber : exit failure 


continued 
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in CX. 


Ce ) ee ee) 


DottedNumber: 


Process 


=e &e fF 


SignatureError: 
Signature: 


sig0: 
sig1: 


repne 
signature 


sige: 


call Number 


je NoNumber 
push cx 

call Dots 

je NumberExit 
pop dx 

call Dot TheNumber 
je NumberError 
ret 


key signature. 


signal BadSignature 


mov ah,' ! 

mov cx, ax 

call NextCharacter 
mov si,ax 

cmp al,'-' 

jz sigO 

cmp al, ‘+’ 

jnz sig1 

mov ch,al 

mov ax,15 


xchg ax,Cx 
mov di,OFFSET Keys 
scasw 


jnz SignatureError 
cmp ah,' ' 

mov ax,si 

jz sig2 


call NextCharacter 
exit success 


ome =e me me =e =e me =e =e 


=e me Se ese 6M Uf we =e -~e 06 =e 


=e we 


=e 88 88 Be Be FO 
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Process a dotted number. A dotted number consists of a number followed 
by 0 or more dots. Each dot scales number by 3/4. Scaled number returned 


Look for number 

If c--no number 

Save number 

Look for one or more dots 
Only number (no dots) 
Recover number 

Scale for dots seen 

If c--number too large 
Return (cx = scaled number) 


Say signature bad 

Assume no sharp or flat follows 
cx <s= key signature 

Get another character 

Save this character 

Is it a flat? 

If Z--it is a flat 

Is it a sharp? 

If NZ--neither sharp nor flat 
Add sharp or flat to signature 
Number of key signatures 


List of valid signatures 
Try to match cx with valid 


If N2--no match 

Did we use this character 
Recover last character 

If Z--last character not used 
Get another character 

and return indicating success 


Process note. Note returns relative position within current scale 
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in CX. 


me =e 


NoNote: 
NoteExitO: 
character 
NoteExit1: 
Note: 


repne 


DoNatural: 


DoSharp: 


DoF lat: 


Process 


Sty leFai lure: 
Style: 


repnz 
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exit 
call 


exit 
mov 
mov 
scasb 
jnz 
call 
cmp 
jz 
cmp 
jz 
cmp 
jnz 
sub 
add 
jmp 
add 
call 
cmp 
jnz 
inc 
jmp 
sub 
call 
cmp 
jnz 
dec 
jmp 


style (MS, MN, 


exit 
mov 
mov 
scasb 
jnz 
call 
mov 


failure 
NextCharacter 


success 
di,CScore.SCR_W_Key 
cx,14 


NoNote 
NextCharacter 
al,'+! 

DoSharp 

al,'-' 

DoF lat 

al, ‘=! 

NoteExit1 

cl,byte ptr (di+13] 
cl,byte ptr [di+27] 
SHORT NoteExitO 
cl,byte ptr [di+13] 
NextCharacter 
al,'+! 

NoteExit1 

cl 

SHORT NoteExit0O 

cl, (di+13) 
NextCharacter 
al,'-' 

NoteExit1 

cl 

SHORT NoteExit0 


or ML. 


failure 
di,OFFSET StyleTable 
cx,1 


StyleFailure 
NextCharacter 
cl,3 


continued 


=e 060 


me we wo 8 =e BH We Be BS BH BS 


=e 88h we =e we 6] 


=e 


=e =e =e 


A ed eT eT) 


Character is not a note 
So AX will have unprocessed 


Return (Found note) 

di <== address of scale 
Number of notes in scale 
See if this is a note 

If NZ--no (not a note) 

Get another character 

Is this a sharp? 

If Z--yes 

Is this a flat? 

If Z-~-yes 

Is this a natural? 

If NZ--not an accidental 
Subtract one if sharped 
and add one if flatted 
Success exit 

Sharp may add one to note 
Get next character 

Double sharp? 

If NZ--no (success exit) 
Double sharp always adds one 
Get next character and exit 
Flat may subtract one 

Get next character 

Double flat? 

If NZ--no (Success exit) 
Double sharp always lowers one 
Get next character and exit 


Say style is invalid 

di <== style table 

Look at first character 

in style table ('M’) 

If NZ--not Music command 

Get next character 

Look at next three characters 
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repnz  scasb 
jnz StyleFailure s If NZ didn't find L, N, or P 
mov cl,es:[dit3] 3 cl <== appropriate style 
call NextCharacter ; Get another character 
exit success : and say we were successful 
CLASSES ENOP 
PAGE 
SUBTTL Utility Routines 
Utility PROC NEAR 
: 
. Save previous byte count and error message. These fields are zeroed when 
: file is opened. We want to be able to return these in response to IOCTL 
; request. Before IOCTL can be issued, another open may have occurred. 
; 
SetDefaults: push es ; Save current ES 
mov cx,cs 
mov es,Cx ; ES <== driver segment 
lea di,PErr 
lea si,CErr 
mov cx,ERR_S Size/2 ; Copy current error to 
rep movsw : previous error 
add si,SCR_S_ Size s si <== Initial CErr value 
mov cx, (SCR_S_Size+ERR_S_Size)/2 : Initialize both SCR and 
rep movsw ; CErr 
pop es 3; Restore ES 
ret s and return 
; 
; Get current INT 8 ISR address 
; 
Get ISR: xor dx , dx s dx <== IVTSegment 
mov es ,dx ; es <== IVTSegment 
assume es:IVTSegment 
les dx,es:Int8Vector s essdx <== Int8 vector 
assume es:_text 
ret 3; and return 
; 
: Set INT 8 ISR to address in ds:ax 


continued 
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e 


SetISR: 
state) 


vector 


=e =e 6M 


SetCount 


me me me 


SetC lock 


progress 


=e =e =e 
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pushf 


cli 


pushr 
xor 
mov 
ASSUME 
mov 
mov 
popr 
ASSUME 
popf 
ret 


Sets 8253 counter 0 to value in AX register. 


erQ: out 
jmp 
xchg 
out 
xchg 
ret 


<dx ,es> 

dx, dx 

es ,dx 

es: IVTSegment 

es:WORD PTR Int8Vector,ax 
es:WORD PTR Int8Vector+2,ds 
<es ,dx> 

es:_text 


18253.Ctr0,al 
SHORT $+2 
al,ah 
18253.Ctr0,al 
al,ah 


Set the clock to run slow (normal speed) 


Slows pushr 
mov 
call 
lds 
call 
or 
and 


popr 
ret 


<ax,ds> 
ax,SlowTickDivisor 
SetCounter0 
ax,cs:OldInt8Vector 
SetISR 


; save current flags (to restore int 
; Disable interrupts while changing 


; Save nonvolatile registers 
3; dx <== IVT Segment 
3; ds <== IVT Segment 


7 Set INT8 ISR OFFSET 
33 and segment 
77 Restore nonvolatile registers 


rz; Restore interrupt state 
3 and return 


; Write LSB of count 

; Delay (for AT) 

; AL <== MSB of count 

: Write MSB of count 

; Return with count intact 


Save nonvolatile registers 

ax <== count down value (64K) 
Use normal countdown value 
dssax <== original int vector 
Make this the int vectir 


cs:DriverStatus,DSS_M_InitNeeded;;; Say vector must change 
cs:DriverStatus,NOT MASK ChangePending;;; and that a change is in 


<ds ,ax> 


:22 Restore nonvolatile registers 


Speed up clock. We make clock tick FastTickCount times faster. We 
do this to increase the resolution in timing note duration. 


continued 


e 


SetClockFast: 


up 


timer 


me te we 8 


DotTheNumber: 
dtn0: 


dtn1: 
dtne: 


Utility 


Actions 


LengthError: 
TempoErrors 
LengthDone: 


pushr 
pushf 
cli 


call 
mov 
mov 
mov 
mov 


call 
mov 
call 
and 
popf 
popr 
ret 


push 
mov 
shr 
shr 
sub 
loop 
mov 
pop 
ret 


ENDP 


PAGE 
SUBTTL 


PROC 
signal 


signal 
job 
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<ax,es> s Save nonvolatile registers 

s Save int enable flag 

3; Disable interrupts while setting 
GetISR Get current int 8 vector 


WORD PTR OldInt8Vector ,dx and save it 
WORD PTR OldInt8Vector+2,es 


ClockTicks, FastTickCount Initialize clock tick count 


ax, FastTickDivisor ax <== Countdown value for 
SetCounter0 373 Set clock fast 

ax, OFFSET CLkISRO 332 Setup new clock ISR 

SetISR 


cs:DriverStatus,NOT MASK InitNeeded ;;; Don't need to change ISRs 
33; Restore interrupt state 
Restore nonvolatile registers 


and return 


<es , aXx> 


Converts a number to a dotted number. Dot count is in CX and number 
is in DX. Dotted number is returned in CX. 


and return 


ax : Save nonvolatile register 

ax, dx 3; Copy of number 

ax,1 3; Number / 2 

ax,1 3 Number / 4 

dx, ax 3 3/4 number 

dtn0 ; More dots to process 

cx, dx s cx <== scaled number 

ax s Recover nonvolatile register 
; 


State Machine Action Routines 


NEAR 

BadLength 3 Say length was bad 
BadTempo ; Say tempo was bad 
cx,MinLength,MaxLength,LengthError ; Range check length 


continued 
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mov 
jmp 
job 
mov 
push 
mov 


TempoDone: 


LtO: 


mov 
div 
(CScore.SCR_W_Length * 


xor 
div 
mov 
mov 
pop 
exit 


; 

: 

; 

: 

NPDoneO: mov 
call 

; 

; 

: 

; 

NPDone1: push 
mov 
mov 
div 
xor 
div 

CScore.SCR_W_Tempo) 
mov 
pop 


=e =e me =e me 
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CScore.SCR_W_Length,cx 

SHORT LtO 

cx,MinTempo,MaxTempo, TempoError 
CScore.SCR_W_Tempo,cx 

ax 

ax, 4352 

dx,1 

CScore.SCR_W_Tempo 


dx , dx 
CScore.SCR_W_Length 
CScore.SCR_W_Ticks,ax 
CScore.SCR_W_NTicks,ax 
ax 

success 


dx,CScore.SCR_W_Length 
DotTheNumber 


ax 
ax, 4352 

dx,1 
CScore.SCR_W_Tempo 
dx , dx 

cx 


CScore.SCR_W_NTicks, ax 
ax 


continued 


mo 06 =e =e 6e =e 


° 
, 
e 
§ 


Save length 

Take common exit 

Range check tempo 

Save tempo 

Save nonvolatile register 
69888 


dx:ax 


Calculate 69888 = 


Zero remainder 


Call result CScore.SCR_W_Ticks 
Update CScore.SCR_W_NTicks too 
Restore nonvolatile register 
and return successfully 


Dotted note or rest. CX has dot count. Length specified by 
CScore.SCR_W Length. Calculate dotted length (result in CX). 


dx <== default note length 
Calc dotted length (cx = dots) 


CX has total length (including dots). Either fall through from NPDoneO 
or called as a result of DottedNumber processing. 


; Save nonvolatile register 


dx:ax 69888 


Zero remainder 


Calculate 69888 + (NoteLength * 


Call result CScore.SCR_W_NTicks 
Restore nonvolatile register 


Either we're using default tick count (CScore.SCR_W_Ticks) or we have 
set CScore.SCR_W_NTicks to proper value. CScore.SCR_W_NTicks is set to 
CScore.SCR_W_Ticks after note has been compiled. 
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NPDone2: exit success ; Exit successfully 


Complete octave processing by checking range and saving value. 


me =e me 


OctaveError: signal BadOctave ; Say octave was bad 
OctaveDone: job cx,MinOctave,MaxOctave,OctaveError ; Check octave range 
mov CScore.SCR_W_Octave,cx ; Save value 
exit success ; Exit successfully 


Complete processing of a note. If it was specified by a letter, convert 
to absolute number by considering octave. Convert absolute note number 
(either letter or Nxx) to pitch. Say there is a valid note. 


me me ee =e =e 


NoteError1: signal BadTie + Say tie is bad 
NoteError: signal BadNote 3 Say this wasn't a note 
NoteDonee: cmp cx,CScore.SCR_W_TFreq 3; Is this note same freq? 
jn2 NoteError1 ; If NZ--No 
exit success ; Tie is good 
NoteDone1: push ax 3 Save nonvolatile register 
dec cx + Tables start with A- instead of A 
mov ax,12 : 12 notes in an octave 
mul CScore.SCR_W_Octave ; ax <== base note of octave 
add CX, ax 3 cx <== absolute note 
pop ax ; Restore nonvolatile register 
NoteDone0: job cx,MinNote,MaxNote,NoteError s Range check note 
mov $i,cx s Convert note to word index 
add si,cx 
mov cx,FreqDivTablelsi] 3 cx <== Frequency Divisor 
mov CScore.SCR_W_NFreq,cx : Save frequency divisor 
test DriverStatus,DSS M_InTie ; Processing tied note 
jnz NoteDone2 : If NZ-~-yes 
exit success : Take successful return 


Complete processing of a rest. Say there is a valid note. 


=e =e me 


PauseDone: or DriverStatus,DSS_M_HasNote 
exit success 


and say we have a complete note 
Take successful return 


Complete processing of style 
continued 
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e 


StyleDone: mov 


exit 


pushr 
mov 
mov 
mul 
add 
mov 
popr 
exit 


SignatureDone: 


Note ends in & 


=e ue =e 


TieError: 
TieDoneO: 


signal 
push 
mov 
add 
je 
or 
mov 
mov 
pop 
exit 
push 
xor 
xchg 


TieDone1: 


add 
je 
and 
or 
pop 
exit 
Actions ENDP 


PAGE 
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CScore.SCR_W_Style,cx 
success 


Complete processing of signature 


<ax , dx> 

ax, CX 

dx ,42 

dx 

ax, OFFSET C 
CScore.SCR_W_Key,ax 
<dx ,ax> 

success 


BadLength 

ax 

ax, CScore.SCR_W_NTicks 
CScore.SCR_W_TTicks,ax 
TieError 
DriverStatus,0SS_M_InTie 
ax, CScore.SCR_W_NFreq 
CScore.SCR_W_TFreq,ax 
ax 

success 

ax 

ax, ax 
ax,CScore.SCR_W_TTicks 


CScore.SCR_W_NTicks, ax 
TieError 

DriverStatus, NOT DSS_M_InTie 
DriverStatus,DSS_M_HasNote 

ax 

success 


continued 


ae me =e =e -e =e me =e 


me we me =e me =e we 


=e =e we me me =e me me ee me me =. 


Record the stype 
and take success exit 


Save nonvolatile registers 

ax <== signature number 

Size of scale + sharps + flats 
Offset of scale 

Address of scale 

Save scale 

Restore nonvolatile registers 
Take successful return 


Note is too long 

Save nonvolatile registers 
Add tick count for this note 
to accumulated ticks 

If C--too big 

Say we're processing a tie 
Remember frequency 


Receiver nonvolatile register 
and exit 

Save nonvolatile register 

New CScore.SCR_W_TTicks value 
New CScore.SCR_W_TTicks <== 0 
AX <== old(CScore.SCR_W_TTicks) 
AX <== Total note Length 
If CY--note too big 

Say no longer in tie 

Say we have a valid note 
Restore nonvolatile register 
Exit successfully 


BufferRoutines 


=e =e 


; SI is current pointer. 
; 
CheckForWrap: cmp $i,OFFSET BUF_W Count 
jl cfwO 
mov si,OFFSET BUF_T_Notes 
cfwO: ret 
; 
; Try to 
; a note 
: 
BufferInsert: cmp BUF_W_Count ,BUF_S_Notes 
jge BufferInsert 
mov di,BUF_A_NextFree 
stosw 
xchg ax ,dx 
stosw 
xchg ax , dx 
xchg di,si 
call CheckForWrap 
xchg di,si 
mov BUF_A_NextFree,di 
inc BUF_W_Count 
ret 
; 
; Remove a note from the buffer. On return, Z= 
; Z=0 ==> we were able to remove a note. DX has 
; has pitch. 
r 
BufferRemove: cmp BUF_W_Count ,0 
jz brO 
mov si,BUF_A_NextData 
lodsw 
mov dx, ax 
lodsw 
dec BUF_W_Count 


SUBTTL Buffer Manipulation Routines 


PROC 


NEAR 


When pointer has reached end of buffer, 
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wrap it around to the start. 


Is pointer at end of buffer? 

If L--not at end 

At end. Wrap to start 

Return with pointer to next item 


insert note into buffer. If the buffer is full, we wait for 
to be removed. AX has note duration and DX has note pitch. 


continued 


ee Se we G8 we 


=e ome 


=e se we 


Is there any room? 
If GE--no room (Busy wait loop) 


di == next free slot 
Store Counter value 
ax <== duration 


Save duration in buffer 


si <== buffer pointer 
Adjust pointer for wraparound 


Update next free pointer 
Say one more note in buffer 
and return 


==> buffer empty. 


me . Tr) 


=e 


oe 


=e Se &e 


duration and AX 


Anything in buffer? 
If Z--no (buffer empty) 


si <== address of next note 
ax <== note duration (ticks) 
dx <== note duration 

ax <== frequency divisor 


One less note in buffer 
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call CheckForWrap ; Make sure pointer wraps at end 
mov BUF_A_NextData,si ; Update pointer 
or si,si ; Return with Z=0 (have data) 


brO: ret 
BufferRoutines ENDP 


PAGE 
SUBTTL Compile and Play Music 


NotePrepPlay PROC NEAR 


me 


Check note status. If we have a complete note, the note state informa- 
tion is converted to a duration and pitch. The converted note is stored 
in the note buffer. 


=e 96 §e fF 


CompileExit: ret 
Compi LeNote: test DriverStatus,0SS_M_HasNote 


Compilation done 
Do we have a valid note? 


~s Se "6 me Be 


jz Compi LeExit If Z-~no note yet 
push ax Save nonvolatile register 
mov ax,CScore.SCR_W_Ticks Set CScore.SCR_W_NTicks = 


CScore.SCR_W_ Ticks 
xchg ax, CScore.SCR_W_NTicks 
xor dx ,dx 
xchg dx, CScore.SCR_W_NFreq 


and ax = old note tick count 
Set Frequency divisor back to 0 
Crest) and dx = old frequency 


me ze =e 


divisor 
mov cx,CScore.SCR_W_ Style 3; cx <== style 
cmp cl,StyleLegato ; Playing in Legato? 
jz cn0 ; If Z--yes (no gap between notes) 
or dx ,dx ; Are we playing a rest? 
jz cn0 ; If Z--yes (no gap between notes) 
mov si,dx ; si <== frequency divisor 
mov dx, ax ; dx <== note duration 
shr dx,cl ; dx <== gap between notes (rest 
duration) 
sub ax, dx ; ax <== audible duration 
xchg dx,si ; dx <== frequency divisor, si 


== (rest duration) 
call BufferiInsert 
mov ax,si 


Insert audible portion in buffer 
ax <== rest duration 
dx <== frequency divisor (0 ==> 


=e 6 OM 


xor dx , dx 
rest) 
continued 


408 


cn0: 
buffer 


cnis: 


=e me =6 me me 


PlayNoteExit0: 


PlayNoteExit1: 


PlayNextNote: 


pni: 


NotePrepPlay 


call 


cli 
cmp 
jnz 
call 
sti 
and 
pop 
ret 


test 
jz 
call 
popr 
ret 
pushr 
in 
mov 
mov 
and 
out 
call 
jz 
or 
jz 
out 
in 
xchg 
out 
xchg 
or 
out 
mov 
jmp 


ENDP 


BufferInsert 


NoteTicks,0 
cn1 
PlayNextNote 


DriverStatus,NOT MASK HasNote 
ax 


Play the next note. If the buffer is empty, 
file. After an end of file and the buffer is empty, 
is set back to slow mode so as not to consume CPU cycles. 


DriverStatus,MASK EOFPending 
PlayNoteExit1 

SetALtISR 

<ds,si,dx,ax> 


<ax,dx,si,ds> 
al, 18255 .PortB 
si,cs 

ds,si 

al, SpeakerOff 
18255.PortB,al 
Buf ferRemove 
PlayNoteExit0 
ax , ax 

pnt 
18253.Ctr2,al 
al, 18255.PortB 
al,ah 
18253.Ctr2,al 
al,ah 

al ,SpeakerOn 
18255.PortB,al 
NoteTicks,dx 
SKORT PlayNoteExit1 


continued 
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Insert legato note or rest into 


Begin critical section 


Is an interrupt expected? 
If NZ--yes 

No note playing. Play one. 
Interrupts ok now 


Say we've played this note 
Restore nonvolatile register 
and return 


check for end of 


=e §e 6G =e me 


=e €@e Me fe 
me me me =e =e =e =e me me oe 


Ce ee ee ee, i et i. ed! 


=“s S86 we BE 


=e 0a 


me Me 
=e =e 


ee se @e -e we 


=e Se SH S28 fe BE 


=e Me 


the clock 


Have we hit end of file? 

If Z--no EOF yet 

Start swap of interrupt vectors 
Restore nonvolatile registers 
and return 

Save nonvolatile registers 

Read current 8255 outputs 

Do this now in case slow adapter 
ds <== 
Turn off speaker 


driver segment 


Get next note from buffer 

If Z--no (buffer empty) 

Is this a rest? 

If Z--yes (Don't enable speaker) 
LSB of frequency divisor 
Overlap with 18253 access 

ah <== 8255 latch settings 
MSB of frequency divisor 

al 8255 latch settings 
Turn speaker back on 


and set durations 
Take common exit 
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PAGE 
SUBTTL Interrupt Service Routines 


ClockISRs PROC NEAR 


Normal ISR when clock is in fast mode. (Clock frequency has been 
increased FastTickCount times). If NoteTicks >0, we are playing 

a note. In this case decrement NoteTicks. If result is 0, its time 
to turn off the speaker and get another note. Every FastTickCount 
times through, we call the old ClockISR to update date and time 
and make any INT 1ch calls. 


=e =e @e8 te 


=e =e fe 


CLkISRO: cmp cs:NoteTicks,0 32; Are we playing a note? 
jz clkO 333 If Z--no 
dec cs:NoteTicks 7; Decrement note count 
jnz clkO 333 If NZ--not at note end 
call PlayNextNote 733 Play another note 
clkO: dec cs:ClockTicks :3; Decrement clock tick counter 
jz clk3 333 Not time to do old clock isr 
ClkIntExit: push ax t37 Save ax 
mov al, EOI 323 Send nonspecific EOI to 
out 18259.PortA,al $33 8259 Interrupt controller 
pop ax rz Restore ax 
iret 33 and exit ISR 
clk3: mov cs:ClockTicks, FastTickCount 3; Reset the counter 
ee 


=e =e =e 


jmp cssOldInt8Vector and call old isr to do int 8 


An end of file was detected and the sound buffer is empty. We are 


e 
; ‘waiting for the ClockTick count to go to 1, so we can put the clock 
; back in slow mode. (If we didn't wait, we would lose an average 
: of 27 ms each time we did change). 
; 
CLKISR1: cmp cs:ClockTicks,1 373 Can we change clock frequency 
yet? 
jl clk2 If L--no must reset ClockTicks 


we =e 


=e =e Sse Be HE 


jo clk1 

call SetClockSlow 

and cs:OriverStatus,NOT MASK Busy 
clki: dec cs:ClockTicks 


If G--not time yet 

Put the clock in slow mode 

Say driver is not busy 

Count one more tick of the clock 


Ce) ee | ee ed 


=e me =e 


continued 
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jmp SHORT ClkIntExit 333 and exit ISR 
clk2: mov cs:ClockTicks, FastTickCount 333 Wait ClockSpeedUp ticks 
jmp SKORT ClkIntExit siz and exit ISR 


; Switch Timer ISR from CLKISRO (Fast clock) to CLkKISR1 (Fast, waiting 

: for tick count to go to 1. 

? 

SetAlLtISR: and DriverStatus,NOT MASK EOFPending ;;; EOF no longer pending 
or DriverStatus,DSS_M_ChangePending ;;; but vector change is 
mOV ax, OFFSET CLKISR1 sz; Have played last note 
call SetISR 333 Swap clock ISR 
ret t33 and return 

ClockISRs ENDP 
PAGE 


SUBTTL Process Driver Requests 


DriverRequest PROC NEAR 


SoundNoP: jmp SuccessExit 

SoundError: mov ax ,DHD_C_ErrUnknownCommand 
jmp DriverExit 

’ 

. IOCTL request processing... 


IOCTL Exits 


Inputs 


bx address of next IOCTL List item 


me me me =e =e =e me 


ItemTooShort: popr <es ,bx, CX> 
ItemBad: mov ax,DHD_C_ErrGeneralFai lure ; ax <== error code 
jmp SHORT ioctl_exit_0 
continued 
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LastItem: mov 
jioctl_exit_O: les 


=e 


=e me =e =e =e me me =e 


me me we ae =e me =e 


les 
sub 
les 
mov 
jmp 


ax ,DHD_M_StsDone 

di,DWORD PTR RqOffset 
di,es:(di].RH_A_BufferAddress 
bx,di 

di,OWORD PTR RqOffset 
es:[di].RH_W_Count ,bx 
DriverExit 


IOCTL Item List Coroutines 


Outputs: 

al item code 

es:di item address 

cx allocated item length 
dx required item length 


Initialize coroutine processing 


Inputs: 


essbx - request header 


FirstItem: pop 


=e me me =e 


mov 
les 


bp 
cx,essRH_W_Count [bx] 
bx,es:{bx] .RH_A_BufferAddress 


Get next list item 


Inputs: 


es: bx 


NextItem: sub 
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jl 
mov 
cmp 
jge 
pushr 
shl 
shl 


next item address 


cx, ITEM_S Size 
LastItem 
ax,es:(bx]. ITEM_W_Code 
al, IOCTL_S_Table 
ItemBad 
<cx,bx,es> 
ax,1 
ax,1 
continued 


=e se we =e =e Se Ge 


=e se Be 


=e me =e me =e 


ax <== successful completion 
es:bx <== request header 
es:di <== ioctl item list 

bx <== bytes processed 

es:di <== request header 
Return count 

Take common driver exit 


bp <== coroutine return 
cx <== size of item list 
es:bx <== item list 


cx <== bytes left in item list 
If L--at end 

ax <== item code 

Is it legal? 

If G--no 


Convert code to word index 


i) 


me 


=e =e we Se w& 


a =n =e me 
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for index 
length of item 


Use si 
ax <== 
si <== address of item 
Is it a string 

If NZ--no 


Save item code 
al <== Length of error text 
Put values where they belong 


s cx <== allocated bytes 


Enough bytes allocated? 
If L--no 
es:di <== item address 


Make coroutine callback 


bp <== callback address 


ds:si <== return length address 
See if return length givem 

(not given if segment = 0) 

If Z--not needed 

Return bytes moved 


bx <== address of next item 
Process next item 


Get first item in List 


mov $i,ax 
mov dx, IOCTL_T_Tablet2[si] 
mov si, IOCTL_T_Tablelsi] 
or dx ,dx 
jnz ni_0O 
mov si, Csi] 
xchg al,dl 
lodsb 
xchg al,dl 
ni_0: mov cx,es:{bx].ITEM_W_Length 
cmp cx, dx 
jl ItemTooShort 
les di,es:{bx).ITEM_A_Address 
call bp 
; 
; Return here to process next item 
; 
pop bp 
popr <es ,bx,cx> 
push ds 
lds si,es:(bx].ITEM_A_RetLen 
mov ax,ds 
or ax , ax 
jz ni_1 
mov [si] ,dx 
ni_1s pop ds 
add bx, ITEM_S_Size 
jmp SHORT NextItem 
: 
: IOCTL processing routines. Input routine (SoundInIOCTL) read 
3 information from device. Information is returned to buffers 
H passed in IOCTL request. Output routine (SoundOutIOCTL) writes 
: information to device. Information comes from buffers passed 
: in IOCTL request. 
’ 
; Inputs: 
: 
: es:bx Request header 
: 
SoundOutIOCTL: call FirstItem 
soi_0: pop bp 


continued 


bp <== callback address 
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rep 


SoundInIOCcTL: 
sii_0: 
rep 


Process 


me mea =e 


Utility 


me me me 


WriteSetup: 


WriteRestore: 


WriteUpdate: 


WriteDone: 
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cmp 
jl 
xchg 
pushr 
popr 
movsb 
mov 
mov 
call 
jmp 


call 
pop 
movsb 
call 
jmp 


al, IOCTL_K_Length 
ItemBad 

si,di 

<ds ,es> 

<ds,es> 


ax,es 
ds,ax 

bp 

SHORT soi_0 


FirstItem 


bp 


bp 
SHORT sii_O 


=e =e ee 


=e =e 88 we 


Legal output item? 
if L--no 
swap es:di and ds:si 


copy item 
restore ds 


get next item 


Get first item in list 
bp <== callback address 
copy item 

Get next item in list 


write requests (Write, WriteVerify, WriteTilBusy,,, 


routines... 


mov 
lds 
mov 
ret 
mov 
lds 
ret 
mov 
mov 
mov 
mov 
mov 
add 
adc 
ret 
mov 
mov 


cx,es: [bx] .RH_W_Count 


si,es:[bx].RH_A_TransferAddress 


cs:SavedDS,ds 


cx, Saved(X 
si,OWORD PTR SavedSI 


dx,cs 

ds ,dx 

es ,dx 

SavedCX, cx 
SavedSI,si 
CErr.ERR_L_Bytes,1 
CErr.ERR_L_Bytes+2,0 


bx,cs 
ds, bx 


continued 


=e te se Se Fs Be we we 


A ed ee) ee, ee ed) 


cX <== transfer size 
dS:SI <== buffer address 
Save xfer buffer segment 
Return (to state machine) 
Restore transfer count 
Restore Buffer offset 

and return 

Reset our data segment 


Update count remaining 

and current buffer offset 

Count total characters transferred 
MSW of character count 

Return to request processing 
Restore driver ds 


les 
sub 


jmp 


=e @e we 


bx, OWORD PTR RqOffset 
es: [bx] .RH_W_Count,cx 
SuccessExit 


Process Write and WriteVeri fy 


SoundWrite: call WriteSetup 
address) 
swO0: lodsb 
call WriteUpdate 
pop bp 
call bp 
call WriteRestore 
Loop swO 
jmp SKORT WriteDone 
: 
: Process WriteTilBusy 


; 

SoundWriteTi lBusy: 
call 

address) 

swi: cmp 
jge 
lodsb 
call 
pop 
call 
call 
loop 
jmp 


SoundStatus: mov 


WriteSetup 


BUF_W_Count ,BUF_S_Notes-1 
WriteDone 


WriteUpdate 

bp 

bp 
WriteRestore 
swi 

SHORT WriteDone 


ax,DHD_M_StsDone 
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3; es:bx <== request header 
Calculate bytes processed 


and take success exit 


; Copy transfer parameters (size and 


Call coroutine 


and process next byte 
Common write exit 


=e 90 we Be 20 Be we 


Is buffer (almost) full? 
If Z--yes (Don't wait) 


Call coroutine 


=e se ©e 28 we MOU lM 


and process next byte 


Assume not busy 

Is buffer full? 

If l--no 

Say operation would wait 
and exit 


Begin critical section 
; Say EOF is pending 


pointers 


e 

cmp BUF_W_Count ,BUF_S_Notes-1 4 

jl ss_0 ; 

or ax, DHD_M_StsBusy 7 
ss_0: jmp OriverExit : 
SoundF Lush: cli ; 

or DriverStatus,DSS_M_EOFPending 

mov BUF_W_Count ,0 

mov BUF_A_NextFree,OFFSET BUF_T_Notes; 

mov BUF_A_NextData,OFFSET BUF_T_Notes 

cmp NoteTicks,0 


continued 


t73 Are we doing anything? 


al <== next byte to write 
Update transfer parameters 
Coroutine callback address 


Restore transfer paramters 


al <== next byte to write 
Update transfer parameters 
Coroutine callback address 


Restore transfer paramters 


HP) 
333 Reset count and buffer 
3 


Copy transfer parameters (size and 
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sf0: 


SoundOpen: 


so0: 


sol: 


SoundC lose: 


DriverRequest 


StgyEntry: 


IntError: 


IntEntry: 
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jnz sf0 3 
call SetALtISR ; 
sti 

jmp SuccessExit 

call SetDefaults ; 
and DriverStatus,NOT MASK EOFPending; 
test DriverStatus,MASK ChangePending ; 
jnz so0 ; 
test DriverStatus,MASK InitNeeded ; 
jz sol ; 
call SetClockFast : 
or DriverStatus,DSS_M_Busy . 
mov 

out 18253 .Mode, al 

mov ax,DHO_M_StsDone ; 
jmp ResetExit . 
mov ax,cs ; 
mov es, ax 

mov al , EOF F 
pop bp ; 
call bp ; 
jmp SuccessExit : 
ENDP 

PAGE 

SUBTTL DOS Entry Points 

mov CS:RqOffset, bx . 
mov CS:RqSegment,es 

return_far ; 
mov ax ,DHD_C_ErrUnknownCommand ; 
jmp ResetExit H 
push_all : 
pushf . 
cld : 
mov ax,cs 7 
mov ds,ax 7 
mov DosSS,ss H 
mov DosSP,sp 

mov SS ,ax ; 


If NZ--yes 
Done. Change to slow mode 


333 Interrupts OK now 


Set driver default values 

EOF is no longer pending 

Is a vector change pending? 

If NZ--yes (wait for it) 

Does clock need to be set fast? 
If Z--no (back to back copies) 
Set clock in fast mode 

Say device is busy 


al,(SetCtr2 SHL SC) OR (LSBMSB SHL RL) OR (Mode3 SHL ™) 


continued 


Say operation was successful 
and reset driver 


Set ES to driver segment 


Tell state machine we're done 
Set up coroutine 

and make call 

Take success exit 


Save request address 


and return to DOS 


Say command is bad 

and reset driver 

Save all registers 

Save flags 

Set direction flag 

Set driver DS 

(00S currently does this for us) 
Save DOS stack 


Establish driver stack 


SoundDispatch: 


SoundInit: 


Copyright 


driver 
_text 


me ue me me me me me 
=s we Me =e 6 @e MO lf 


we me me =e =e me =e 


we us ae me =e =a 


mov 
les 
mov 
cmp 
jge 
cbw 
add 
mov 
jmp 


mov 
mov 
or 
mov 
mov 
int 
mov 
jmp 
DB 
DB 
DB 
endp 
ends 
end 


MACROS .ASM 
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sp,DriverSP 

bx,DWORD PTR RqOffset 
al,es:Cbx].RH_B_Command AL <== command 

al,RQ@_S Table Is it in range ? 

IntError ; If GE--out of range 

Make command a word 

Convert to word index 

SI <== function table index 
Dispatch on function code 


Set SP to where we Left off 
es:bx <== Request Header 


=e se me Be 


ax, ax 
si,ax 
RQ_T_Tablelsi] 


=e | 06@e me ~ 


we 


WORD PTR es:({bx].RH_A_BreakAddress, OFFSET SoundInit 
WORD PTR es:[bx+2).RH_A_BreakAddress,cs 
DriverStatus,DSS_M_InitNeeded 
dx,OFFSET Copyright 

ah,9 

2th 

ax, DHD_M_StsDone 

ResetExit 

BELL,"SOUND v2.0",CR,LF 

"© W. V. Dixon 1987",CR, LF 

u ALl rights reserved",CR,LF,'$! 


begin 


Common device driver macro definitions 


© 1987 W. V. Dixon. ALL rights reserved. 


May be freely copied for personal, nonprofit use 

so long as this copyright notice is retained and usage 
restrictions are observed. This software may not be 
used in whole or in part in any program which is sold 
without prior written consent of the author. 
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He Macros for pushing and popping registers 

3 

-? 

He Push an arbitrary number of registers 

‘ 

pushr MACRO x 33 x is register list 

3: (enclosed within ©) 

IRP y ,<Xx> 3s: For all registers in list 
push y 33; Push it on the stack 
ENOM 27 IRP 
ENDM :; MACRO pushr 

a 

° Push all registers onto stack 


Hr 
push_all MACRO 
pushr <ax,bx,cx,dx,di,si,bp,ds,es> 


ENDM :; MACRO pusha 

3 

a Pop an arbitrary number of registers 

te 

popr MACRO x 3s; x is register list 

33 (enclosed within ©) 

IRP y ,<Xx> 33; For all registers in List 
pop y 3; Pop the register 
ENDM 37 IRP 
ENDM 3; MACRO popr 

as 

:7 Pop all registers from stack 

a 

pop_all MACRO 
popr <es,ds,bp,si,di,dx,cx,bx,ax> 
ENDM 3; MACRO popa 


es 
ve 


continued 
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Macros for near and far returns 


return_far MACRO 
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DB Ocbh 3; Opcode for far return 
ENOM 7? MACRO return_far 


return_near MACRO 
DB Oc3h zs 
ENDM ae 


=e =e 


Macros for return with status 


me me =e me me =e 


; 

; cY=0 ==> SUCCESS 

; CY=1 ==> FAILURE 

; 
exit MACRO x a 


IFIDN <x>,<success> 
cle 


ELSE 33 x iS not success 
IFIDN <x>,<failure> 73 If x is failure 
stc 33 Set CY=1 
ELSE 77x is not failure 
OUT "Invalid exit argument - failure assumed"' 
stc 
ENDIF 33 x is not failure 
ENDIF 37x iS not success 
ret 7; Return with status in carry 
ENOM 73 MACRO exit 
a 
re Unconditional return with failure status 
ie 
ret_failure MACRO x 73 x iS argument count 
stc 33 Say we failed (CY=1) 
ret x 3; and return 
ENOM 33 MACRO ret_failure 
ret_success MACRO x 7? x iS argument count 
cle 33; Say we succeeded (CY=0) 
ret x 33 and return 
} ENDM 7; MACRO ret_success 


Opcode for near return 
M 


ACRO return_near 


x is success or failure 
37 If x is success 
Set CY=0 


continued 
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me 


Macro to do range check 


owe fe 


If value is Less than minvalue or greater than maxvalue, 
jump to outrange; otherwise fall through to next statement 
unless inrange is not blank. If inrange is not blank and 


=e we we OF 


value is within range, jump to inrange. 


.- =e se Fe Be Se We BH GE 
me 


job MACRO value,minvalue,maxvalue,outrange, inrange 
cmp value, minvalue 3; Value less than minimum? 
jl outrange 2: If L--yes (jump outrange) 
cmp value,maxvalue 3; Value greater than maximum? 
jg outrange s: If G--yes (jump outrange) 
IFNB <inrange> s; If inrange label is specified 
jmp inrange ss Jump to it 
ENDIF 33 Inrange nonblank 
ENOM ¢¢ MACRO job 

Hn 

, Macro to trace driver execution 


ee 


trace MACRO msg Message to display 


=e) 6 
=e we 


LOCAL x We need some local labels 
LOCAL y 
jmp SHORT x 3; Jump over text 
y dB msg 3; Define message text 
0B Odh,Oah, '$' s2 Append <CR><LF> and ''3'' 
x: pushr <ax,dx,ds> s+ Save nonvolatile registers 
pushf 3; Remember flags 
mov ax,cs 
mov ds,ax ds <== current CS 


a 
33 (message segment) 
A 


mov dx ,OFFSET y dx <== message address 


mov ah,9 s: Issue bios request to display 
int 21h 3; Message 

popf :: Restore flags 

popr <ds ,dx ,ax> 3; Restore registers 

ENDM 3; MACRO trace 


continued 
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DEVICE.DEF 


en eS eT 


Common device driver definitions 


=e =e me =e =e 


=. 


© 1987 W. V. Dixon. ALL rights reserved. 


May be freely copied for personal, nonprofit use 

so long as this copyright notice is retained and usage 
restrictions are observed. This software may not be 
used in whole or in part in any program which is sold 


=s se ee =e Me Me le 
me me me =e ee =e =e 


without prior written consent of the author. 


me me 


me =e 


Bit settings for device header (DHD) attributes word 


me =e Ge 
=e we we 


DHO_M_IsCharacter EQU 8000h =;; Character device 
DHO_M_IsBlock EQu QO0Oh ;; Block device 
DHD_M_IOCTLSupport EQU 4000h ;; Supports MS-DOS IOCTL functions 

33 CINT 21H AH = 44H) 
DHD_M_NonIBMFormat EQu 2000h = ;; Media is not IBM format compatible 
DHD_M_I8MFormat EQU OOOOh ;; Media is IBM format compatible 
DHD_M_WriteBusySupport EQu 2000h 3; Write until busy supported 
DHD_M_IsNetwork EQu 1000h j;; Network device 
DHD_M_OCRMSupport EQU O800h ;; Open / Close / Removable media 

33 supported 
DHD_M_LogDevSupport EQu 0040h ;; Get / Set logical device supported 
DHD_M_IsSpecial EQU 0010h 3; Supports INT 29H output 
DHD_M_IsCurClk EQU O0O8h 5; Device is current clock 
DHD_M_IsCurStdout EQU O004h = ;; Device is current stdout 
DHD_M_IsCurStdIn EQU 0002h ; Device is current stdin 
DHD_M_IsCurNul EQU CO001h Device is current nul 


DHD_M_GenIOCTLSupport EQU 0001h Supports MS_DOS generic IOCTL function 


CINT 21H AX = 440DH) 


—-e =e Be fe 
~e we fe 


me 
=e 


continued 
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33 Successful completion 


73 Device is currently busy 


3; Unsuccessful completion 


3 Driver return status values 

HH (MSB of Request Header status word) 
a? 

DHD_M_StsDone EQU 100h 
DHO_M_StsBusy EQU 200h 
DHD_M_StsError EQU 8000h 

an 

3 Specific driver error codes 

os (LSB of Request Header status word) 


DHO_C_ErrWriteProtect EQU 
DHD_C_ErrUnknownUnit EQU 
DHD_C_ErrNotDriveReady EQu 
DHD_C_ErrUnknownCommand EQU 


DHD_C_ErrcRC EQU 
OHD_C_ErrBadStructure EQU 
OHD_C_ErrSeek EQU 


DHD_C_ErrUnknownMedia EQuU 
DHD_C_ErrSectorNotFound EQU 


DHD_C_ErrPaperOut EQU 
DHO_C_ErrWriteFault EQu 
DHD_C_ErrReadFault EQU 


DHD_C_ErrGeneralFailure EQU 
DHD_C_ErrInvDiskChange EQU 


Device Header (DHD) 


me Me ft 
me me =e 


DHD STRUC 
DHD_A_NextDHD dd 
DHO_W_Attrib dw 
DHD_W_StrategyEntry dw 
DHD_W_InterruptEntry dw 
DHD_T_Name db 
DHD ENDS 


Request Header (RH) 


=e me we 
we =e - 


es 
ee 
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DHO_M_StsError OR 0 
DHD_M_StsError OR 1 
DHD_M StsError OR 2 
DHD_M_StsError OR 3 
DHD_M_StsError OR 4 
DHD_M_StsError OR 5 
DHD_M_StsError OR 6 
DHD_M_StsError OR 7 
DHD_M_StsError OR 8 
DHD_M_StsError OR 9 
DHD_M_StsError OR Qah 
DHD_M_StsError OR Obh 
DHD_M_StsError OR Och 
DHD_M_StsError OR Ofh 


- Oo Oo O&O 


me @~e Mel MO 
me me ee ee me 


continued 


=e =e as me =e =e =e =e 


=e =e =e =e me 


=e =e te te Se Be GO 


me me =e =e =e me =e 


Write protection error 
Illegal unit number 
Drive is not ready 
Illegal driver command 
CRC error on drive 

Bad request structure length 
Error on seek 

Media unknown 

Sector not found 

No paper in printer 
Error writing 

Error reading 

Catchall error 

Invalid disk change 


Address of next device 
Device attributes 

Offset to strategy routine 
Offest to interrupt routine 
Device name 
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Generic request header. Directly used for: 


=e =e =e 
me me =e =e 


Input Status (RH_C_InputStatus) 
: Input Flush (RH_C_InputFlush) 
ee Output Status (RH_C_OutputStatus) 
oF Output Flush (RH_C_OutputF lush) 
. Device Open (RH_C_Open) 
: Device Close (RH_C_Close) 


Removable Media (RH_C_RemovableMedia) 


=e Se we we 
=e 6% 


RH STRUC 

RH_B_Length DB 0 :3 Length (bytes) of request 
RH_B Unit DB 0 7; Unit code 
RH_B_Command dB 0 :; Command code 
RH_W_Status DW 0 3; Status 
RH_T_ReservedDOS 0B 8 DUP(O);; Reserved for 00S 

RH ENDS 

te 

os Request Header commands 

ve 

RH_C_Init EQU COH ; Device initialization 
RH_C_Media EQU O1H 3 Media check 


=e §e fe 


=e Se Be Be Bell CU 


RH_C_Bui LdBPB EQu 02H 
RH_C_InputIOCTL QU O3H 
RH_C_Input EQU O4H 
RH_C_InputNoWait EQU O5H 
RH_C_InputStatus EQU O6H 
RH_C_InputFlush  EQU O7H 
RH_C_Output EQU 08H 
RH_C_OutputVerify EQU O9H 
RH_C_OutputStatus EQU OaH 
RH_C_OutputFlush EQU ObH 
RH_C_OutputIOCTL EQU OcH 


Build BIOS Parameter block 
Input IOCTL 

Input 

Nondestructive input 
Input status 

Input flush 

Output 

Output and verify 
Output status 

Output flush 

Output IOCTL 


=e =e =e me ee me =e 


=e =e me 


en) ee ee 


RH_C_Open EQU OdH 73; Device / File open 

RH_C_Close EQU OeH 7; Device / File close 
RH_C_Removeabl eMedia EQU OfH 3; Check for removable media 
RH_C_OutputTi LBusy EQu 10H ?; Output until busy 
RH_C_GenIOCTL EQu 13H 7; Generic IOCTL request 
RH_C_GetLogDevice EQU 17H 7; Get Logical device 
RH_C_SetLogDevice EQuU 18H 77 Set logical device 


continued 
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=e 


Initialization request (RH_C_Init) 


=e =e @e 


RH_INIT STRUC 

DB TYPE RH DUP(O) 
RH_B_UnitCount DB 0 3; Number of units 
RH_A_BreakAddress 0D 0 33 Ending address of driver 
RH_A_BPBTable DD 0 :; Pointer to 8PB array 
RH_B_Orive DB 0 s; Drive number 
RH_INIT ENDS 
ve 
as Media Check (RH_C_Media) 
is 
ie 
Ae Returned MediaStatus values 
3 
RH_C_MediaChanged EQU “1 3; Media has changed 
RH_C_MediaNotChanged EQU +1 3; Media has not changed 
RH_C_MediaNotSure EQU O ;; Not sure whether media has 

7; changed 

RH_MEDIA STRUC 

DB TYPE RH DUPCO) 
RH_B_MediaCode DB 0 ;; Current media code 
RH_B_MediaStatus 08 0 3; Media status 
RH_A_MCVolumeID ODD 0 3; Pointer to volume id 
RH_MEDIA ENDS 
ve 
es Build BIOS Parameter Block (RH_C_BuildBPB) 
a 
RH_BUILD_BPB STRUC 

DB TYPE RH DUPCO) 

DB 0 3; Current media code (RH_B_MediaCode) 
RH_A_BufferAddress DD 0 3s; Buffer address / FAT Sector 
RH_A_BPB DD 0 33 Address of BPB table 
RH_BUILD_BPB ENDS 


continued 
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=e 


Input or output request. Used for: 


me ee 
me =e 06 me me 


; Input (RH_C_ Input) 
; Output (RH_C_Output) 
Hr Output and Verify (RH_C_OutputVeri fy) 
33 Input IOCTL (RH_C_InputIOCTL) 
ae Output IOCTL (RH_C_Output IOCTL) 
A Output til busy (RH_C_OutputTi lBusy) 
re 
RH_1IO STRUC 

DB TYPE RH DUP(O) 

DB 0 :; Current media code (RH_B_MediaCode) 
RH_A_TransferAddress DD 0 :3 Transfer address 
RH_W_ Count DW 0 3; Byte/sector count 
RH_W_Sector OW 0 :; Starting sector 
RH_A_VolumeID DD 0 3; Pointer to volume id 
RH_IO ENDS 


Nondestructive Input No Wait (RH_C_InputNoWait) 


me me me 
=e e668 


RH_RNW STRUC 
0B TYPE RH DUP (O) 

RH_B_ByteRead DB 0 7; Byte just read 
RH_RNW ENDS 

rr) 

3; VALUES.DEF 

; 

; Specifies min/max, constants, and default values for 


SOUND driver. 


; 
; © 1987 W. V. Dixon. ALL rights reserved. 
; 


continued 
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me =e ue ee . 
e« 0 %e es we Bs 


MinTempo 
MaxTempo 
MinOctave 
MaxOctave 
MinLength 
MaxLength 
MinNote 
MaxNote 


BUF_S_Notes 


StyleLegato 
Sty leNormal 
StyleStaccato 


SCR_K_DLength 
SCR_K_DOctave 


SCR_K_DTempo 
SCR_K_DKey 


SCR_K_DStyle 
SCR_K_OTicks 


FastTickCount 


EQU 
EQU 


EQU 


EQU 


EQU 
EQU 


EQU 


FastTickDivisor EQU 


SlowTickCount 


EQU 


SlowTickDivisor EQU 


426 


64 


88 


120 
OFFSET C 


Sty leNormal 
146 


1000h 


May be freely copied for personal, 


=e =e (fe 


nonprofit use 


so long as this copyright notice is retained and usage 
restrictions are observed. This software may not be 
used in whole or in part in any program which is sold 
without prior written consent of the author. 


Minimum tempo 

Maximum tempo 

Lowest octave 

Highest octave 

Longest note (whole) 
Shortest note (sixty-fourth) 
Lowest note 

Highest note 


Internal buffer size 


Play Legato 
Play Normal 
Play Staccato 


; Default note Length (quarter-note) 


Default octave 

(octave above middle C) 
Default tempo 
(quarter-notes per second) 


; Default key 


Default style 
Default note length in ticks 
69888 + (DefaultTempo * DefaultLength) 


Speed up timer by factor of 16 
Counter preset for speedup 
Normal timer 


: Counter preset for normal speed 


continued 
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HARDWARE . DEF 


Hardware definitions for SOUND driver 


=e me me =e me 
me me ee me me 


© 1987 W. V. Dixon. All rights reserved. 


May be freely copied for personal, nonprofit use 

so long as this copyright notice is retained and usage 
restrictions are observed. This software may not be 
used in whole or in part in any program which is sold 
without prior written consent of the author. 


=e te @e Se B06 Be Be Be fe 


me me m6 me =e =e me =e 


8259 Interrupt Controller 


me =e me 
=e =e lf 


18259 EQU 20H ;; Base address 

EOI EQU 20H 7; Nonspecific end of interrupt 
3; control word 

2 

ne 8255 PPI 

+? 

18255 EQU 60H 3; Base address 

PortA EQU 00 33; Port A offset (base = 0x60) 

PortB EQU 01 7; Port B offset (base = 0x61) 

PortC EQu 02 3; Port C offset (base = 0x62) 

Control EQU 03 33; Control port (base = 0x63) 


=e 


=e ze =e 


Speaker control 


me =e 


PBO Record SpeakerData:1,SpeakerGate:1 
SpeakerOn EQU MASK SpeakerData OR MASK SpeakerGate 
continued 
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SpeakerOff EQU NOT SpeakerOn 


8253 Timer / Counter 


me me me 
=e $e te 


18253 EQU 40H 3; Base address 
CtrO EQU 0 3; Counter 0 (base = 0x40) 
Ctr1 EQU 1 3; Counter 1 (base = 0x41) 
Ctr2 EQU 2 33 Counter 2 (base = 0x42) 
Mode EQU 3 :3; Control (base = 0x43) 
Hn 
Hi Control word format 
3 
ModeWord Record SC:2,RL:2,M:3,8CD0:1 
ve 
33 Control word values 
ee 
CounterLatch EQU 0 
MSBOnLy EQU 2 
LSBOnly EQU 1 
LSBMSB EQU 3 
SelCtrO EQu 0 
SelCtri EQU 1 
SelCtr2 EQu 2 
ModeO EQU 0 
Mode‘ EQU 1 
Mode2 EQU 2 
Mode3 EQU 3 
Mode4 EQU 4 
Mode5 EQU 5 
FSM. DEF 


mo ee Me MO 
=e @e me fe 


Macros for generating state transition table 
continued 
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=e 
=e 


ie 

HA © 1987 W. V. Dixon. All rights reserved. 

A 

33 May be freely copied for personal, nonprofit use 

7 so long as this copyright notice is retained and usage 

3 restrictions are observed. This software may not be 

He used in whole or in part in any program which is sold 

HH without prior written consent of the author. 

te 

i 

HH Macros for generating state labels 

‘7 

‘? 

Hr Generates label for current state 

tt 

this_s MACRO x 3; Create Label for 

s_&x: 77 S_Xxx (current state) 
ENDM 7; MACRO this_s 

4 

HH Generates label for next state 

i 

next_s MACRO x 7, Generate reference to 
OW s_&x 72 S_Xxx (next state) 
ENDM 73 MACRO next_s 

‘7 

Hi Define state table entry 

a 

FSM STRUC 3; Define state table entry 

FSM_A_Class DW 0 3; Class processing routine 

FSM_W_Data OW 0 ;; Class data 

FSM_A_Nstate DW 0 i; Next state 

FSM_A_Action DW 0 3; Action routine 

FSM_A_Ntrans DW 0 7? Offset of next transition 

FSM ENDS 


continued 
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=e me me 
me we =e 


nnn=0 


=s we we 
ue =e me 


tran 


=e =e fF 
=e =e 8 


state 


430 


State definition counter 


Define transition macro (tran) 


MACRO 
OW t_class 
IFNB <t_name> 

DW t_name 
ELSE 

DW 0 
ENDIF 
IFNB <t_nstate 

DW t_nstate 
ELSE 

next_s 4nnn 
ENDIF 
TFNB <t_action> 

DW t_action 
ELSE 

DW 0 
ENDIF 
ENDM 


Define state macro (state) 


MACRO sname 


ee 
ae 
ee 
ae 


oe 
ee 


=e %e Ge Se We 
=s %e %e Se we 


=e =e =e =e =e 
=e =e se we we 


=s =e =e =e =e 
=n me me =e me 


Make sure state count 
set to 0 


t_class,t_name,t_nstate,t_action 


Class always present 


Name is optional 
Use it if present 
Otherwise 

say not present 
IFNB <t_name> 


Next state optional 

Use next state if present 
Otherwise 

Default to next state 
IFNB <t_state> 


Action routine optional 
Use it if present 
Otherwise 

say no action routine 
IFNB <t_action> 


: MACRO trans 


State macro definition 
continued 
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IFE nnn 33 If first invocation 
s_exit: tran exit_success,0,0 ;; Make sure that s_exit defined 
nnn=1 i; We've defined one state 
s_fail: tran exit_failure,O,0 ;; Make sure s_fail defined 
nnn=2 3; We've defined two states 
ENDIF 3; IFE nnn 


tran exit_failure,0,0 Final transition for previous 


Lr) =e 


state. (Forces error exit 
; because no matching transition) 


IFNB <sname> If optional name present 


. =e =e me =e =e me 
« 


; 
sname: ; Define it as a symbol 
ENDIF ; IFNB <sname> 
this_s annn ;; Always define s_xxx style name 
nnn=nnn+1 +; One more state defined 
ENDM :: ENDM state 
ar] 
ss Define state end (state_end) macro 
Hr Forces completion of last state (specifically appends 
re failure transition to previously built transition table). 
ae 
state_end MACRO 3; Declare end to state table 
state 73; Final state forces last tran 


ENDM 3; For previous state to be 
3; defined 


An executable version of the SOUND driver and all driver source code 
is available on IBM 5-4” DSDD diskette. Also included on this diskette are 
sources and executables for DEVICES and a self-loading RAMdisk device 
driver. These are written primarily in Microsoft C. All the programs on this 
disk have been tested under PC-DOS version 3.10. The author believes they 


work correctly but makes no guarantees to this effect. The software is pro- 
vided strictly on an as-is basis and you are using it entirely at your own risk. 
The author will assume no responsibility for any damage that the software 
may cause. All code carries a copyright notice similar to the SOUND driver 
in this essay. The diskette is available for $10.00 (check or money order) 
from Walter Dixon; RR#2, Box 581; Delanson, NY 12053. 
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Essay Synopsis: The Enhanced Graph- 
_. ics Adapter (EGA) has effectively become the 


standard for graphics on MS-DOS systems. 


‘Although many programming languages 
- contain high-level graphics routines, direct 
"access to the EGA registers and memory is 
_ -. needed for many demanding applications. 
_- . Due to its increased capabilities, the EGA is 
considerably more complex to program 
than arethe CGA or monochrome displays. 
~ . You will learn how to program the EGA 
“. .. through basic routines for reading and writ- 
ing pixels, drawing lines, printing the 
screen, and setting the color palette regis- 
_. ters: The examples use access through C 
-. “ pointers, but the same principles can be 
_- used by programs in assembly or other lan- 
. guages. The author also discusses perfor- 
‘mance considerations. 


12 


Programming the Enhanced 
Graphics Adapter 


coor oe fet ceinameteecrar herd vae 


err lenny ae an 


Andrew Dumke 


The Enhanced Graphics Adapter (EGA) has established a new standard for 
high-resolution graphics on the IBM PC and compatibles. The EGA is more flexi- 
ble and powerful than the Color Graphics Adapter (CGA) it replaces, but also 
more complex to program. This paper is intended to show how to program the 
EGA, the similarities and differences between it and previous adapters, and a 
few graphics routines to make using the EGA much easier. Basic graphics rou- 
tines will be presented for reading and writing pixels, drawing lines, printing the 
screen, and manipulating the palette registers. As each of these routines is de- 
veloped, the different methods of controlling the color and shapes written to the 
EGAs memory will be covered. These concepts are easily extended to a future 
programming project of your own. 


Inside the EGA 


Most of the routines in this paper use EGA output ports and direct memory ac- 
cess for maximum performance. Although there are more than 60 EGA output 
registers, the few ports covered here are enough for most programming proj- 
ects. The EGA BIOS is also more involved than the few calls covered here would 
indicate, but not many graphics programs need to use any more than the most 
basic BIOS functions. 

While many of the improvements over the CGA have to do with text, only 
the EGA graphics modes will be examined in detail. Every code listing in this 
paper is EGA-specific, and does not apply at all to the CGA. The routines use C 
pointers for direct memory access. If pointers are unfamiliar to you, you may 
want to brush up on them before modifying any of these routines. 
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Compiling the Examples 


The examples included were developed using Microsoft C version 4, and Borland's 
Turbo C version 1. These two compilers are source code compatible. There may be 
some syntactic differences with other compilers but the concepts are the same. All 
the EGA functions have been separated into separate C functions. As you read this 
paper, keep two separate files. The first, ega.c, should contain the EGA C functions 
covered in this paper. Each code listing has a comment to remind you to add the 
functions to ega.c that are used later. The second file, ega.h, will contain the func- 
tion prototypes for the functions in ega.c and EGA-specific macros. 

Once ega.c has been compiled, the EGA-specific functions in ega.obj may 
be called by any program by linking that program with ega.obj. 


Microsoft C 


To compile all examples under Microsoft C, use: 


MSC example.c /W 3; 
LINK example ; 


The /w3 compiler switch turns on strong type-checking to help you catch er- 
rors. If you keep the EGA functions in a separate source code file, compile with 
these statements: 


MSC ega.c /W3 ; 
MSC example.c /W 3 ; 
LINK example + ega ; 


If you use Microsoft C version 3.0, add the /Ze compiler switch to enable the far 
keyword. 


Borland Turbo C: 


The Borland Turbo C compiler will compile and link in a single step. To compile 
with Turbo C, use: 


TCC EXAMPLE 

If you keep the EGA functions separate, use: 

TCC EXAMPLE EGA 

where EXAMPLE is the file with your code, and EGA contains EGA-specific graphic 


functions. Strong type-checking is the default with Turbo C so no compiler 
switches are necessary. 
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History of the EGA 


IBM introduced the EGA in 1984. It is well on the way to becoming the dominant 
color graphics display adapter for the IBM PC. The EGA is compatible with the 
two other popular IBM display adapters, the CGA and the Monochrome Display 
Adapter (MDA). With the introduction of the new PS/2 systems, IBM introduced 
three new video standards: the MCGA on the PS/2 model 30, the Video Graphics 
Array (VGA) on all other PS/2s, and the optional high-resolution 8514/A. The 
MCGA is compatible with the older CGA standard but not the EGA. The VGA and 
8514/A both support most EGA programs. The MCGA may be upgraded to a 
VGA. Essentially, the EGA is the new lowest common denominator for IBM color 
graphics, replacing the older CGA. 

The original EGA from IBM comes with 64K of graphics memory on the 
card which may be expanded in 64K increments to 256K. The more EGA mem- 
ory, the greater the graphics capabilities. EGA compatible cards from other 
manufacturers often come with the full 256K memory already installed. 

Video functions on the IBM PC are called with the BIOS Interrupt 10h. 
These video functions allow a program to set text or graphics modes, read or 
write single pixels, and place characters on the screen. The EGA has a new BIOS 
that replaces all the original PC video functions, and adds several new BIOS 
functions. The new EGA functions allow new characters to be defined, more 
control over the palette, and text strings to be printed. Several of the new BIOS 
function calls relating to graphics will be covered later, but the new EGA BIOS 
calls for text functions will not be covered in this essay. 


Monitors and EGA Capabilities 


The EGA is designed to work with one of three different monitors—the IBM 
Color Display (CD), the IBM Enhanced Color Display (ECD), or the IBM Mono- 
chrome Display (MD)—and their equivalents from other manufacturers. The 
monitor used determines the graphics resolution, the maximum number of col- 
ors, the color palette, and the number of pixels that make up each character. 

The IBM Color Monitor has a maximum resolution of 640x200 pixels. The 
Color Monitor is limited to 200 scan lines vertically by only being able to use one 
vertical scan rate. The EGA is compatible with all the text and graphic modes of 
the Color Graphics Adapter when used with the Color Monitor. There are two 
new graphics modes, modes 13 and 14, that use up to 16 colors with 320x200 and 
640x200 resolution. However, the Color Monitor is limited to a 16-color fixed pal- 
ette and 200 scan lines vertically. The fixed palette uses the same 16 colors used 
by the CGA in text mode. The default character box is 8x8 pixels. The modes 
available with the IBM Color Monitor are listed in Table 12-1. 
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Table 12-1. IBM Color Monitor Modes 


Mode Maximum Size Box Maximum Buffer 

Number Type Colors (Col. X Row) Size Pages Segment Resolution 
0 Text 16 40x25 8x8 8 B800 320x200 
1 Text 16 40x25 8x8 8 B800 320x200 
2 Text 16 80x25 8x8 4/8/8* Bs00 640x200 
3 Text 16 80x25 8x8 4/8/8* B800 640x200 
4 Graphics 4 40x25 8x8 1 B800 320x200 
5 Graphics 4 40x25 8x8 1 B800 320x200 
6 Graphics 2 80x25 8x8 1 B800 640x200 
13 Graphics 16 40x25 8x8 2/4/8* A060 320x200 
4 Graphics 16 80x25 8x8 1/2/4* Aoco 640x200 


* Depends on amount of installed EGA memory 


Enhanced Color Display 


The IBM Enhanced Color Display is compatible with all the modes used with the 
Color Monitor, and uses one more high-resolution mode. The Enhanced Color 
Display is able to use two vertical scan rates, one for 200 line modes and one for 
350 line modes. The new multisync-type monitors are able to use the two stan- 
dard EGA-generated vertical scan rates as well as even higher frequencies for 
higher resolution. The high-resolution mode, mode 16, can be used only with the 
IBM Enhanced Color Display, an equivalent monitor, or a multisync monitor 
since the vertical resolution is 350 scan lines and the Color Display can only dis- 
play 200 lines. The EGA can display 16 colors from a 64-color palette in most 
modes when used with the Enhanced Color Display. The 16 colors are only avail- 
able in mode 16 if there is more than 64K on the EGA card. Modes 4 through 6, 
the CGA compatible graphics modes, are limited to the same 16-color fixed pal- 
ette as the CGA. The text modes on the Enhanced Color Display use 8x14 pixels 
for each character, which gives a higher-resolution character than used on the 
CGA. The modes for the Enhanced Color Display (and multisync equivalents) are 
listed in Table 12-2. 


Monochrome Graphics Modes 


The IBM Monochrome Display is used primarily as a text-only display. The text 
mode is compatible with the IBM Monochrome Adapter. However, there is a new 
mode that adds 640x350 graphics with four “colors”: black, video, flashing 
video, and intensified video. If a Monochrome Monitor is connected to the EGA, 
it is unable to use any of the color graphics modes, but may use the new mono- 
chrome graphics mode. 

The EGA converts the 8x14 font used with Enhanced Color Monitor into an 
MDA-compatible 9x14 font. This is accomplished by extending any line draw 
characters into the 9th pixel position. 
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Table 12-2. Enhanced Color Display Modes 


Mode Maximum Size Box Maximum Buffer 
Number Type Colors (Col. X Row) Size Pages Segment Resolution 
0 Text 16 of 64 40x25 8x14 8 B800 320x350 
1 Text 16 of 64 40x25 8x14 8 B8s00 320x350 
2 Text 16 of 64 40x25 8x4 4/8/8* B800 640x350 
3 Text 16 of 64 80x25 8x4 4/8/8* B8s00 640x350 
4 Graphics 4 40x25 8x8 1 B800 320x200 
5 Graphics 4 40x25 8x8 1 B800 320x200 
6 Graphics 2 80x25 8x8 1 B800 640x200 
13 Graphics 16 of 64 40x25 8x8 2/4/8* A000 320x200 
14 Graphics 16 of 64 80x25 8x8 1/2/4* AOoo 640x200 
16 Graphics “sof 64* 80x25 8x14 1/2° AOo0 640x350 


* Depends on amount of installed EGA memory 


The addition of multiple video pages is a subtle change in the standard 
MDA mode 7, the text mode, with the EGA. The original Monochrome Adapter 
uses only one page. The EGA can store up to eight individual video pages, de- 
pending on the amount of EGA memory. The page number is specified in the 
8086 register BH when using the BIOS functions for text. If older software uses 
BH for other data, or fails to initialize it, the final text output may not appear on 
the desired page. 

EGA-compatible cards from other manufacturers may offer a Hercules- 
compatible graphics mode when used with a Monochrome Display. The two 
modes for the Monochrome Display are listed in Table 12-3. 


Table 12-3. Monochrome Display Modes 


Mode Maximum Size Box Maximum Buffer 

Number Type Colors (Col. X Row) Size Pages Segment Resolution 
7 Text 4 80x25 9x14 4/8* BooOo 720x350 
15 Graphics 4 80x25 8x14 1/2* AOGO 640x350 


* Depends on amount of installed EGA memory 


Installation Considerations and Presence Test 


Notice that the capabilities of the EGA are dependent on the monitor and the 
amount of memory on the EGA board. The monitor determines which video 
mode to use for graphics or text, and the amount of EGA memory determines 
the number of colors and pages available. It is very important for your programs 
to determine whether there is an EGA present in the PC before you try to use it, 
and which monitor and memory were used if one is found. 
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EGA BIOS routine: Return EGA Information (INT 0x10) 


The program we will show next does just that. The function get_ega_info(&info) 
is called with a pointer to a structure to hold EGA information. The function first 
retrieves a byte from the BIOS data area. That byte, at 0x40:0x87, has encoded 
information about the EGA hardware configuration, memory, and monitor. It is 
one of several status bytes kept by the EGA BIOS for its internal use and to provide 
information to programs. The bits we are interested in are bits 5 and 6 which indi- 
cate total EGA memory, bit 3 which indicates whether the EGA is the active display, 
and bit 1 which indicates the type of monitor. The Function calls one of the EGAs 
new BIOS calls, alternate Function 10, which returns EGA information. This func- 
tion is called by placing 0x12 in register AH and 0x10 in BL, and using INT 10H. Since 
the PC's BIOS does not use a video function 0x12, this call can be used as an EGA 
presence test. The PC's BIOS will safely reject unknown INT 10H calls with the regis- 
ters unchanged, so if the outgoing registers are unchanged by the call, or the in- 
coming registers do not match the data in the EGA information byte, there is simply 
no EGA present. Here is the EGA BIOS call which returns the information: 


Call with: AH = 0x12 To Select EGA Alternate Functions 
BL = 0x10 Alternate Function for EGA Information 


Returns: BH = O = Color Monitor 
1 = Monochrome Monitor 
BL = Encoded EGA Memory: 


0 = 64K 
1 = 128K 
2 = 192K 
3 = 256K 


CH = Feature Bits 
CL = EGA Board Switch Settings 


The egacheck.c Program and Macros 
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This program will check for an active EGA display card. (There may be another 
display card in the system. If another card is active, bit 3 of the byte at 0x40:0x87 
will be 1.) If an active EGA card is found, some information about the setup is 
saved. 

Notice the macro PEEK_BYTE(seg,off), which allows this program to re- 
trieve a byte from anywhere in the PC’s memory. It works by shifting the value 
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for the segment left one word (16 bits), and then bit ORing the offset to form a 
long int. This long int is then cast to a far pointer. 

Also notice the definition #define LINT_ARGS. If you wish to use the 
Microsoft C's built-in lint on the library functions, you must define this before all 
the #include directives. You also must compile with the /w3 compiler option to 
use the Microsoft lint. With LINT_ARGS at the top, before the #includes, the com- 
piler will check all library function calls for argument-type agreement and num- 
ber of arguments. 


/* egacheck.c */ 

/* Checks for an EGA */ 

/* If one is found, information is saved */ 

#define LINT_ARGS /* Enable strong type checking */ 
#include <conio.h> 

#include <dos.h> 

#include <stdio.h> 


#define PEEK_BYTE(seg,off) \ 
(x(char far *) (€ Clong) (seg)<<16 | (off) > ) 


/* Add this template to "ega.h" */ 
struct Ega_info 
{ 
char monitor ; /* to hold the type of monitor */ 
int memory ; /* amount of memory: 64, 128, 192, 256K */ 
char high_res_graphics ; 
char text_mode ; 
, ae /* Template to hold information about EGA */ 


/* Add this function prototype to "ega.h" */ 
int get_ega_info(struct Ega_info *) ; 


main() 
{ 
struct Ega_info info ; 


if (get_ega_info(&info)) /* test for EGA */ 
{ 

printfC("\n\nEGA in use.) ; 

printf("\nConnected to a!) ; 

switch(info.monitor) 

{ 

case ‘C's: puts(" Color Monitor’) ; 
break ; 
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case ‘M's: puts('' Monochrome Monitor") ; 


break ; 

case ‘H's: puts(''n Enhanced Color Monitor") ; 
break ; 

default: break ; /*x undefined */ 


} 

printf ('\n%ik bytes of EGA Memory.", info.memory) ; 

printf(''\nMode %#2i is the highest resolution graphics mode.", 
Cint)info.high_res_graphics) ; 

printf ("\nMode 4#2i1 is the text mode.\n\n", 
Cint)info.text_mode) ; 


} 
else 
puts("\nNo active EGA.") ; 
} /* End of main() */ 


int get_ega_infoCinfo) 
struct Ega_info *info ; 


/* This function tests if an active EGA is in the system */ 
/* Add this function to ega.c */ 
/* Be SURE to use "get_ega_info(&info)" IE USE THE "&! 

IN FRONT OF "INFO! x/ 


union REGS regs ; 
int i; 

/* Get the EGA information byte from the BIOS data area */ 
char bios_info = PEEK_BYTE(0x40,0x87) ; 


/* Bit 3 indicates if the EGA is active or not 
**x it is NOT a test for presence */ 
if(bios_info & 0x8) 
return (0) ; /x if bit 3 is 1, EGA is NOT active */ 


regs.h.ah = Ox12 ; /* EGA Alternate BIOS Function */ 
regs.h.bl = 0x10 ; /* Get Info */ 

regs.h.bh = OxFF ; /* An impossible return value */ 
int86(0x10, &regs, &regs) ; /* EGA BIOS Video Call */ 


/* bios_info bits 5 + 6 and BL(encoded EGA memory) and */ 

/* bios_info bit 1 and 8H must be equal if there is an EGA */ 

if(Cregs.h.bl != ((bios_info & 0x60) >> 5)) |! /* Memory */ 
Cregs.h.bh != (Cbios_info & Ox2) >> 1)) |! /* Monitor */ 
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} 


Cregs.h.bh == OxFF)) 
return(Q) ; /* if any test 


/* OK, there is an EGA, save 
/* The monitor type code is: 

'C' for color, 

‘'M' for mono, 

‘H' for highres */ 
switch(regs.h.cl) /* cl has t 
{ 

case Q: /* mono primary, 

case 6: /* mono second, 
info->monitor = 'C’ ; 
info->high_res_graphi 
info->text_mode = Ox1 
break ; 

case 1: /* mono primary, 

case 2: /* same as 1 */ 

case 7: /* mono second, 

case 8: /* same as 7 */ 
info->monitor = ‘C' ; 
info->high_res_graphi 
info->text_mode = 0x3 


break ; 
case 3: /* mono primary, 
case 9: 

info->monitor = ‘H' ; 


info->high_res_graphi 
info->text_mode = Qx3 
break ; 
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/* BH != FFE */ 
fails, return, no EGA */ 


the type of monitor */ 


he EGA switch settings */ 


EGA color 40x25 */ 
EGA color 40x25 */ 


cs = OxD ; 


EGA color 80x25 */ 


EGA color 80x25 */ 


cs = OxE ; 


EGA high res */ 


/* EGA high res primary, mono second */ 


cs = 0x10 ; 


e 


case 4; /* color 40 primary, EGA mono */ 
case 5: /* color 80 primary, EGA mono */ 
case 10: /* EGA mono primary, color 40 second */ 
case 11: /* EGA mono primary, color 80 second */ 


info->monitor = 'M’ ; 
info->high_res_graphi 
info->text_mode = 0x7 

break ; 
default: 
return (0) ; 

+ 


cs = OxF ; 


/* Reserved Switch Settings */ 


/* EGA is active in this system, return the memory */ 
return(info->memory = 64 * (regs.h.bl + 1) ) ; 
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EGA BIOS Routine: Write Dot (INT 0x10) 


Now that we know what mode to use for graphics, we can draw something on 
the display. The EGA BIOS has the same write dot call as the PC BIOS. This call is 
slow, but usable on all IBM graphics cards. Here is the specifics of the EGA BIOS 
Write Dot: 


Call With: AH = OxC To Select Write Dot Function 
BH = Page 
DX = Row Number 
CX = Col Number 
AL = Color Value 


Returns: Nothing 


Notice the addition of a page value in BH. If you are converting older soft- 
ware to run on the EGA, make sure the page number is in BH before calling INT 
10H. Programs written for the monochrome adapter, or the CGA in graphics 
mode, are especially vulnerable to this oversight. 

The BIOS call to switch to a graphics mode is precisely the same as on the 
PC, namely Function 0 of INT 10H. However, the BIOS does not check that the mode 
you select will not damage your monitor. A monochrome monitor, connected 
to an EGA, may be damaged by a color text or graphics mode signal, so it is 
important to check for monitor and mode compatibility. The function 
get_ega_info(&info) from the EGACHECK program is used to check the moni- 
tor and find the high-resolution mode that is safe to use. The program in the 
next listing demonstrates the use of set_crt_mode() to set a graphics mode, and 
dot () which uses the BIOS write dot function. The program will draw a series of 
parallel diagonal lines. 


/* diagonal.c */ 

/*x Demonstrates the EGA high res graphic mode */ 
#define LINT_ARGS 

Hinclude <conio.h> 

#include <dos.h> 

#include <stdio.h> 

#include 'ega.h"' 


void set_crt_mode( char ) ; /* Add this to "ega.h" */ 
void dot( int, int, int, int ) ; 


main() 
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register i,j ; 
struct Ega_info info ; 
if(get_ega_info(&info)) 
set_crt_mode(Cinfo.high_res_graphics) ; 
else 
return(1) ; 


for(j O; j <= 500; j += 5) 
for(i O; i <= 100; ++i) 
dot(i,itj,13,0) ; 
getch() ; /x wait for a character to be typed */ 
set_crt_modeCinfo.text_mode) ; 


void dot (row,col,color,page) 
int row, col, color, page; 


{ 
union REGS regs ; 
regs.x.dx = row ; 
regs.x.cx = col ; 
regs.h.al = (char)color ; 
regs.h.ah = (char)OxC ; /* Write Dot call */ 
regs.h.bh = (char)page ; /* NEW TO THE EGA! */ 
int86(0x10, &regs, &regs) ; 
} 
/ SSS Sow eee ee See eS SsSSSsSsSessssssssassessasy / 


void set_crt_mode (mode) 
/* Add this function to ega.c */ 
char mode ; 


{ 
union REGS regs ; 
regs.h.al = mode ; /* al=mode to set */ 
regs.h.ah = (char)0O ; /* Set Mode Function */ 
int86(Ox10, &regs, &regs) ; /* execute BIOS int 10h */ 
} 
/ SS SSS SSSSSSSSSSSSSSSSSSS2S55SSS5S552555=25>5% / 


When you see how slow the BIOS write dot function is, you will probably 
wonder about making it faster. To do that requires bypassing the EGA BIOS and 
putting pixels directly into the EGA’s memory. However, you first must under- 
stand how the EGA’ memory is organized, and how to control it. 
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Memory Organization 


The EGA uses two different display memory organizations for graphics. In 
modes 4 through 6, the EGA uses the same memory organization as the CGA. In 
these modes, the display memory segment starts at 0xB800 and uses 80 bytes 
per scan line. Since there are 200 scan lines, 16,000 bytes are used. In the me- 
dium resolution 320x200 mode, each byte represents four pixels with one of 
four colors, or two bits per pixel. In mode 6, each byte represents eight pixels 
with two colors, or one bit per pixel. If a bit is 1, the corresponding pixel is on, 
and if a bit is 0 the corresponding pixel is off. Additionally, the even-numbered 
scan lines are in the first 8K of the display memory, and the odd-numbered scan 
lines are in the second 8K of memory. The split scan line memory requires every 
pixel’s offset to be tested if it is in the even or odd bank. 

The display memory for modes 13 through 16 starts at segment OxA000 and 
uses up to 64K of the 8086 CPU address space. (Where is the 256K of EGA mem- 
ory I paid for? More on that in a minute.) Each byte represents eight pixels with 
the most significant bit being the leftmost. The scan lines are not separated in 
memory like they are in the CGA modes, so the byte offset of a pixel is easier to 
calculate. In mode 16, the EGA has a maximum resolution of 640x350, or 
224,000 pixels. Since there are up to 16 colors, each pixel uses four bits to specify 
the color. This is a total memory usage of (640 x 350 pixels + 8 pixels/byte x 4 
bits/pixel + 1024 bytes/K) = 109K. But the 8086 CPU used in the PC can only 
address a segment of 64K. The EGA fits into the 64K segment limit by dividing 
128K of its 256K memory into four 32K bit planes. Each bit plane (or bit map) 
corresponds to one bit of a pixel’s color. Imagine these four bit planes as being 
stacked on top of each other at the same CPU address. Each CPU display mem- 
ory address is actually four bytes of EGA memory. 


Latch Registers 


Reading or writing four different bytes (one for each bit plane) at the same ad- 
dress presents a problem. To overcome this problem, the EGA has four latch reg- 
isters. These hold one byte from each of the four bit planes temporarily. Each of 
the four latch registers is filled with a byte from each of the bit planes at the 
address last read by the CPU. When the CPU sends a byte to the address last 
read, each of the four latch register contents may be unchanged, modified, or 
entirely replaced by the CPU data. The latch register contents are then written 
back to the EGAs bit planes. When the latch registers are written back to the 
EGAs bit planes, they are again “stacked,’ with each bit of the four bytes forming 
the four-bit color for eight pixels. The relationship between the latch registers 
and the bit planes is shown in Figure 12-1. The state of the EGAs memory and the 
contents of the four latch registers after the CPU reads the byte at A000:0000 
are represented. The 8 pixels in the byte contain colors 0 through 7. It is impor- 
tant to understand that the byte returned to the CPU after reading A000:0000 
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has no use. That byte is read only to establish which pixels to work with (in this 
case pixels 0 through 7 in row 0), and to “prime” the latch registers, allowing the 
individual bytes of the bit planes to be manipulated by CPU data. Then the eight 
pixels contained in the four bytes can be modified, replaced, or cleared by the 
PC’s CPU. To work with pixels in a different row or column, the offset from A000 
is changed and a new byte containing the pixels is read by the CPU. 


Bit Plane 3 


Bit Plane 2 


Bit Plane 1 


Aoco:ccco | 0/1] 0]1]0]1] 0/1 | Bit Plane 0 


_— -=90-00 —_— 


fols fol: folifols}y 


Pixel Position 


Fig. 12-1. EGA bit maps and latch registers. 


Whether the latch registers are modified, replaced, or unchanged by the 
CPU depends on the settings of several EGA control registers. These registers 
are accessed through one of five indexed Very Large Scale Integration (VLSI) 
chips on the EGA. These VLSI chips are set by sending an index number corres- 
ponding to the function desired, followed by the data for that function. Essen- 
tially, the index corresponds to one of many registers internal to ihe EGA, but 
mapped to a single PC output port. Data for these registers are sent using the 
8086 OUT instruction or the C library’s outp( function. For example, the EGA has 
a bit-mask register that will allow individual bits of the latch registers to be pro- 
tected from change. Setting a bit to 0 in this register masks out the correspond- 
ing bit in the latch registers, and setting a bit to 1 allows that bit to be changed by 
CPU writes. The bit-mask register allows individual pixels to be changed with- 
out altering an adjacent pixel's address by the byte. In other words, the bit-mask 
register allows individual pixels to be changed rather than the entire byte full of 
pixels. The bit-mask register is Function number 8 on the EGA’s Graphics ~ 1&2 
chip. It is programmed by sending an index of 8 to port 0x3CE followed by the 
bit-mask data to port 0x3CE The following C statements would set the bit-mask 
register to protect all bits except bit 2: 
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outp(Ox3CE, 8) ; /x The index of the bit mask */ 
outp(Ox3CF, Ox2) ; /x All bits, except bit 2, to 0 */ 


But these statements give no clue, except for the comments, to what they do. In 
the next section, we will cover a C macro to make setting the EGA registers easier. 

A second EGA register that affects how the latch register contents are re- 
written is the map-mask register. If any of the four bits of the map-mask register 
are zero, the corresponding bit maps are protected from change. Sending a 
number between 0 and 15 to the map-mask register will allow that color corres- 
ponding to that number to be written to the EGAs bit planes. However, the previ- 
ous contents of the bit maps are not cleared, and must be before setting the map 
mask—but after setting the bit mask—by writing a zero to the byte containing 
the pixel to change. The map-mask register is part of the EGA’s Sequencer chip. 
It is accessed by sending the index of 2 to port 0x3C4 and sending the map mask 
to port 0x3C5. The effects of the bit mask and the map mask, setting pixel 2 on 


. map 0, 2, and 3, are shown in Figure 12-2. 
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Fig. 12-2. Bit-mask and map-mask registers. 


With these two registers, and an understanding of the EGA latch registers, 
we have enough information to create a routine in C that will directly write a dot 
into screen memory. This routine is faster than the same routine in the EGA’ 
BIOS. On an 8MHz AT, the EGA BIOS will put 2.65 dots on the display in one 
millisecond (2.65 dots/ms). The routine in the listing in the next section 
FASTDOT.C puts 7.55 dots/ms on the display, or an increase in speed of 185 per- 
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cent. The drawback is that fastdot () will work only in EGA graphics modes and 
would have to be rewritten for another display card. 


More Macros 


The first thing we need to do is define some routines to access the EGA’s VLSI 
controllers. These macros will allow the routine to set the bit mask, the map 
mask, and other internal EGA registers. 


H#define EGA_GRFXCindex, value) { outp(Ox3CE, index) ; \ 
outp(Ox3CF, value) ;} 

#define EGA_SQNCCindex, value) { outp(0x3C4, index) ; \ 
outp(Ox3C5, value) ;} 


The first macro, EGA_GRFX, takes as arguments the index number corresponding 
to the function desired on the Graphics ~ 1&2 controller chip, as well as the 
value to send to the chip. The EGA’s Graphics 1&2 chips control the access to the 
bit planes. Although there are actually two chips at the same address, you can 
treat the Graphics ~ 1&2 chips as one chip. The address to index the Graph- 
ics ~ 1&2 chip is Ox3CE, and the data address is Ox3CF The macro expands into 
two C statements. The first statement sends the index value to the chips using 
the library function outp(). The second statement sends the data. 

The second macro, EGA_SQNC, is similar to EGA_GRFX. However, EGA_SQNC ac- 
cesses a different chip, the EGA’s Sequencer chip, by sending the index and data 
to different output ports. The Sequencer chip's main interest here is the map- 
mask register. 

The next two macros will allow the routine to access a segment:offset ad- 
dress anywhere in the PC's address space: 


H#define PEEK_BYTE(s,o) (*(char far *) ( (long) (s)<<16 ' (0) ) ) 


H#define PEEK_WORD(s,o) (*(int far *) (€ (long) (s)<<16 ! (0) ) ) 


The final macros give a name to some common uses of the previous 
macros. The GET_CRT_COLS() macro returns the value to use for the number of 
bytes per line in the EGA graphics modes. EGA_BIT_MASKand EGA_MAP_MASKset the 
bit-mask and the map-mask registers, respectively. 


#define GET_CRT_COLS() PEEK_WORD(0x40, Ox4a) 
H#define EGA_BIT_MASK(mask) EGA_GRFX(8, mask) 
H#define EGA_MAP_MASK(mask) EGA_SQNC(2, mask) 


These macros make the following code written to manipulate EGA hard- 
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ware far easier to read and understand. The six macros: EGA_GRFX, EGA_SQNC, 
PEEK_BYTE, PEEK_WORD, EGA_BIT_MASK, and EGA_MAP_MASK should be added to ega.h. 
These macros are used in all the routines in the rest of this paper. 


/* fastdot.c */ 
#Hinclude <conio.h> 
#include "ega.h" 


fastdot(row, col, color) 
/* add this function to ega.c */ 
/* This routine will put a dot in the EGA's display buffer 
**x Use only in EGA graphics modes (13,14,15, or 16) 
** and on an EGA with 128K memory or greater */ 
int row, col, color; 
{ 
char Latch ; 
/*x establish the address of the byte to change */ 
/* buffer byte is AQQO: (Crow * bytes/row) + col/8) */ 
unsigned char far *rgen = (char far *)(OxAOOCOOOOL + 
(col >> 3) + 
(row * GET_CRT_COLS()) ) ; 
/* Calculate the bit to change: */ 
char bit_mask = (char) (0x80 >> (col & 7)) ; 


EGA_BIT_MASK(bit_mask) ; /* set the bit mask */ 
Latch = *(rgen) ; /* prime the EGA latches */ 
*(rgen) = 0 ; /*x clear the bit */ 
EGA_MAP_MASK(color) ; /* set the color */ 

*(rgen) = OxFF ; /* set the bit */ 
EGA_MAP_MASK(OxF) ; /* reset the map mask */ 
EGA_BIT_MASK(OxFF) ; /* reset the bit mask */ 


Write-Only Register in the EGA 


Notice the last two lines where the map mask and the bit mask are reset. The 
majority of EGA registers are write-only. Any concurrent or subsequent pro- 
gram that uses the display needs to make assumptions about the state of the 
EGA, because a write-only register cannot be read. Therefore, the safest state to 
leave the EGA registers in is the EGA BIOS default state. Additionally, the EGA 
BIOS assumes the EGA registers are in the default state when writing characters 
on the display. If the bit-mask register is set to mask bits, the characters will be 
unreadable. For the bit mask and the map mask, the default is no mask at all, soa 
“mask” of OxF and OxFF restores the default state. 


450 


Chapter 12: Enhanced Graphics Adapter 


Also notice how the byte address of the pixel is calculated: 


char far *rgen = (char far *)(OxAOOQOOOOL + 
(col >> 3) + 
Crow * GET_CRT_COLS()) ); 


The address of the byte is ((row x bytes per row) + cols + 8 bits per byte). For 
the division of cols by 8, C's shift right operator, the >> is used for greater speed. 
Since 8 = 2 X 2 x 2 = 2 ¢¢ 3, then cols + 8 = cols )) 3. To calculate the 
number of bytes per row, which can be 40 bytes in video mode 13 or 80 bytes in 
modes 14 through 16, look at the number of characters per row in the BIOS data 
area (address 0x40:0x4A). The number of bytes per row and the characters per 
row are the same in the EGA graphics modes. The result of the total calculation 
is added to OxAOQOOOOOOL, which is the segment of the EGA graphics modes. The 
entire value is then cast to a far pointer. 

The bit number in the byte that corresponds to the pixel to change is calcu- 
lated by (col~&~7). Once the bit number is known, the bit mask is set to 0x80 )) 
bit number. The value 0x80 is 010000000b. 

The routine above assumes that page Ois used. To add the ability to address 
a page other than page 0, add these lines: 


while(page) { 
rgen += PEEK_WORD(Ox40, Ox4c) ; /* add the page length */ 
--page ;} 


where page is the number of the page to address. The word at 0x40:0x4C con- 
tains the length of the CRT Display buffer in bytes used by the EGA’s BIOS rou- 
tines. 

Try the DIAGONAL.C program after replacing dot with fastdot (). It is two to 
three times faster than the BIOS routine. 


Lots of Dots 


For maximum performance on the EGA, many functions need to be written to 
take advantage of unique EGA hardware. For example, the fastdot routine above 
set the bit mask and map mask to the needed values at the beginning of the rou- 
tine, then reset those registers to the BIOS default state at the end. If a function 
calls the fastdot routine repeatedly, the register reset at the end of the fastdot 
routine is repeated unnecessarily. That slows the function down. The program 
BRES .C shown next includes a line drawing routine that is based on Bresenham’s 
Algorithm. Bresenham’s Algorithm was originally used to control digital plotters, 
but it is equally suited for bitmap CRT graphics. The algorithm always incre- 
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ments (or decrements) by 1 in either the x or y direction. The x or y direction is 
selected by the magnitude of the slope of the line. If the rise (y direction) is 
greater, increment (or decrement) y; if the run (x direction) is greater, increment 
(or decrement) x. Whether to increment or decrement x and y is decided by the 
direction of the line. A cumulative error term is used to decide when to incre- 
ment or decrement in the perpendicular direction. Instead of calling the fastdot 
routine above, the dots are placed on the display directly. The EGA registers are 
reset only once at the end, and the function is much faster than the same one 
written based on a calling fastdot(). 


/* bres.c */ 

/* Draws a pattern to demonstrate the line() function */ 
#define LINT_ARGS 

#include <conio.h> 

#include <dos.h> 

H#include <stdio.h> 

#include "ega.h" 


void LineCint,int,int,int,int) ; /* Add this to ega.h */ 
/xnesssassaessssssssarsssssaassesssssssnssssSsSsaSssSssSaaasaak / 


int x1, y1, x2, y2; 
int step = 10, color = 13, scan_lines ; 
struct Ega_info info ; 


if(get_ega_info(&info) >= 128) /* Active EGA? Memory? */ 
{ 
set_crt_mode(info.high_res_graphics) ; 
scan_lines = (PEEK_BYTE(Ox40, 0x84) + 1) 
* PEEK _WORD(Ox40, 0x85) ; 
y2 = (scan_lines - 1) - ((scan_lines - 1) % step) ; 
for (y1 = 0, x1 = 0, x2 = 0; 
y1 <= ye; 
y1 += step, x2 += step) 
Line(x1,y1,x2,y2,color) ; 


getch() ; /* Wait for a key press */ 
set_crt_mode(info.text_mode) ; 
} 
else 


puts("\nEGA adapter not active or not installed.\n") ; 
} 
/ ear eee ese sess ssseresssaSeessssSSssaSSsSSsssssrSsaaak / 
void Line(x1,y1,x2,y2,color) 
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int x1,y1,x2,y2,color ; 

/* A fast Line function - uses Bresenham's algorithm. */ 
/* rowCly's) and col(x's) and are assumed not equal */ 
Adefine sign(x) (C(x) <0) 7? (-1) : (1)) 

#define qabs(x) (((x) < 0) ? -(x) =: (x)) 

{ 

int dx = qabs(x2 - x1) 3 /* run */ 

int dy = qabs(y2 - y1) ; /* rise */ 

int s1 = sign(x2 - x1) 3; /* direction to increment/decrement */ 
int s2 = sign(y2 - y1) ; 

int dx2, dy2, bytes_per_line = GET_CRT_COLS() ; 

register error_term, i ; 

unsigned char far *rgen = (char far *)(OxAOGOQOOOL) ; 
unsigned char exchange = (char)O ; 


/* The larger of rise or run determines 
**x which to increment in the loop */ 
if(dy > dx) 
{ int temp = dx; dx = dy; dy = temp; exchange = (char)1; } 


dx2 = (dx << 1) ; /* Used repeatedly, calculate now */ 
dy2 = (dy << 1) ; /* Use shifts for speed */ 
error_term = (dy - dx) << 1; /* Initialize error_term */ 
EGA_GRFX(O, color) ; /* Use the EGA's Set/Reset Register */ 
EGA_GRFX(1, OxF) ; /* Enable all bit planes */ 
for Ci=1; i<=dx; ++i) /* ALL the pixels along the Line */ 

{ 

EGA_BIT_MASK(Ox80 >> (x1 & 7) ) ; 

rgenC ((x1 >> 3) + Cy1 * bytes_per_line)) ] += Ox1 ; 

while Cerror_term >= 0) /* Loop until another pixel */ 


{ 
if Cexchange) 

x1 += sl ; 
else 

y1 += s2 ; 
error_term -= dx2 ; 
} 
if (exchange) 

y1 += s2 ; 
else 

x1 += s1 ; 
error_term += dy2 ; 

} 
EGA_GRFX(1, QO) ; /* Disable the Set/Reset register */ 
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EGA_BIT_MASK(OxFF) ; /* Reset the bit mask */ 
} 
/xkBBBSSSS Sse ReSsssSSSsSssesssssSSs SSeS SSSSSSSaSSSSSsSSSseTs=SH=xk / 


To keep the graphic image on the screen, a program should have the height 
and width of the display in pixels. The width is given by GET_CRT_COLS() * 8 pix- 
els/byte. The height could be determined exactly with a table containing scan 
line counts for each mode. However, there is a quicker but less accurate way. 
Both the number of character rows and the point size (bytes per character) are 
programmable on the EGA, and therefore, either one can change. The height, 
however, of the character box in bytes and the number of scan lines determine 
the number of rows. Since the word at 0x40:0x85 has the bytes per character 
and the byte at 0x40:0x84 has the number of rows, they can be used to calculate 
the number of scan lines for any video mode. The C statement: 


scan_lines = (PEEK_BYTE(Ox40, 0x84) + 1) 
* PEEK_WORD(Ox40, 0x85) ; 


calculates the approximate value for total scan lines—approximate since the 
number of rows is rounded down and may or may not be off by 1. Once the EGA 
data are known, the program draws a pattern of lines that is independent of the 
EGA graphics mode used. 


Using the Set/Reset Register 


The Line function uses a different method to specify the color of dots on the 
display than the fastdot () routine. The fastdot() routine uses the map-mask 
register to specify the color, but since specifying a mask to the map-mask regis- 
ter does not clear the previous dot, the dot must be cleared with the map mask 
first reset to OxF and then set to the color of the new dot. In other words, both 
the map mask and EGA memory must be accessed twice for every dot to set to a 
specific color. The tine() function uses the set/reset register and the enable set/ 
reset register to specify the color. The set/reset register will set a byte to OxFF in 
each EGA bit plane where a bit is on in the set/reset register, and will reset a byte 
to Oin each EGA bit plane where a bit is off. Therefore, the previous contents of 
the latch registers are replaced with the color number corresponding to the 
value set in the set/reset register. The map-mask register has no effect on the set/ 
reset register but the bit-mask register is usable to protect adjacent pixels. To 
use the set/reset register, you must first enable it with the enable set/reset regis- 
ter. The BIOS default state for the enable set/reset register is 0, which means that 
the set/reset register is turned off. Each bit of a four-bit value sent to the enable 
set/reset register corresponds to an EGA bit plane. If a bit in the enable set/reset 
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register is 0, the corresponding bit plane is protected from change by the set/ 
reset register. The set/reset register and the enable set/reset register are part of 
the EGAs graphics controller. The set/reset register is accessed by first sending 
an index of 0 to port 0x3CE, then sending the four-bit color code to port 0x3CE 
The set/reset register only affects the bit planes enabled in the enable set/reset 
register. The enable set/reset register is accessed by sending an index of 1 to port 
Ox3CE, then sending the four-bit map mask to port Ox3CF. 

Notice the statement rgenl ((x1>>3) + (y1 * bytes_per_line)) ] += Ox1 ;. 
Since the EGA display buffer is linear, it can be easily addressed as an array. The 
expression inside the brackets calculates the buffer offset of the byte to change. 
The right side of the statement would seem to be adding 1 to that byte, and that 
is what the CPU thinks it is doing. However, the actual purpose is to preserve the 
adjacent pixels contained in the byte. When the bit-mask register is used, the 
display buffer must be read first to fill the latch registers so that the other bits in 
the byte may be preserved. Unlike the map-mask register, when the set/reset reg- 
ister is used, the byte sent by the CPU has no meaning beside establishing ad- 
dressability of the byte to change. So the += 1 does two things: It reads the display 
buffer in order to prime the latch registers, and then sends a byte back which 
triggers the set/reset register. The 1 could be any value as long as the C compiler 
translates the operation into an 8086 instruction that first reads and then stores 
a byte in the EGAs display memory. 


Using the EGA Write Modes 


The EGA has three write modes: 0, 1, and 2. Changing the EGA write mode will 
change the way EGA hardware reacts when the CPU sends a byte to the display 
buffer. Each write mode is optimized for a different use. Write mode 0 is the 
general-purpose write mode, write mode 1 is optimized for copying EGA mem- 
ory regions, and write mode 2 is best used for color fills. Changing the write 
mode can speed up an operation dramatically. 

Write mode 0 is the mode used by the EGA BIOS. It is the most general- 
purpose write mode. In write mode 0, the color of a pixel may be set by using 
either the map-mask register or the set/reset register. The map-mask register is 
used by the EGA BIOS and by the fastdot() routine. The line() function uses 
the set/reset register to specify a color. When using the map-mask register, indi- 
vidual pixels may be set by the CPU sending a byte, with the corresponding bits 
in the byte set to 1. However, adjacent pixels in the byte must be protected with 
the bit-mask register. When using the set/reset register, the bits in a CPU byte 
sent to the EGA display do not correspond to pixels. The byte is written only to 
determine the offset of the pixels to change. The color is specified in the set/ 
reset register, and the bit-mask register allows individual control of pixels. 

Write mode 2 is the most similar to write mode 0. Write mode 1 has a spe- 
cial use and will be covered later. In write mode 2, the byte sent from the CPU 
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sets the color rather than individual pixels. The bit-mask register gives control 
over individual pixels, and, if the bit-mask register is not set, the entire byte of 
pixels is filled with the color from the CPU. The write mode is specified in bits 0 
and 1 of a byte sent to the mode register on Graphics ~ 1&2 chips. The index of 
the mode register is 5. The program rect.c shown next demonstrates write 
mode 2. The rect() routine uses write mode 2 to fill a rectangle with a given 
color. 


/* rect.c */ 

/x this program demonstrates write mode 2 */ 
#define LINT_ARGS 

#Hinclude <conio.h> 

#include <dos.h> 

#include <stdio.h> 

H#include "ega.h" 


void rect(int,int,int,int,char); /* add to ega.h */ 


main() 
{ 
int i,j; 
set_crt_mode(16); /* Make sure you have the 
** right monitor/memory! */ 
printf("\nColor #:\n"); 
for (i=0, j=0; 1<16;++i, j+=40) 
{ 
printf(' 42) ",i); 
rect (50, j ,349, j+39, (char) i); 
} 
getch(); 
set_crt_mode(3) ; 
} 


void rect (row1,col1,row2,col2,color) 
int col1,row1,col2,row2 ; 
char color ; 
/* add this function to "ega.c" */ 
{ /* This Function generates a filled rectangle */ 
/* It is assumed that row1 < row2, and col1 < col2 */ 
unsigned char far *rgen = (char far *)(OxAQOOOO00L) ; 
int rows = row2 - rowl ; /* number of rows */ 
int cols = (col2 >> 3) - (col1 >> 3) - 1 3 /* total columns */ 
char Left = (char) (OxFF >> (col1 & 7)) ; /x left bit mask */ 
char rght = (char)~(OxFF >> (col2 & 7)) 3; /* right bit mask */ 
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char next_row ; 

char bytes_per_line = (char)GET_CRT_COLS() ; 
register x,y ; 

char latch ; 


if (cols <0) /* Test if col1 and col2 are in the same byte */ 
left &= rght, cols = 0, rght = 0; 

rgen += bytes_per_line*rowl + (col1 >> 3) ; /* EGA offset */ 

next_row = bytes_per_line - cols - 2; /* next row offset */ 


EGA_GRFX(5,2); /* Set Write Mode 2 */ 

forty = 0 3 y < rows ; y++) /* do every row */ 

{ 
EGA_BIT_MASK(left) ; /* Set the bit mask for left */ 
latch = *(rgen) ; /*x Latch the EGA bit planes */ 
*(rgent+) = color ; /* Set the color, point to next byte */ 


EGA_BIT_MASK(OxFF) ; /* No mask in the center */ 
for(x = 0; x < cols; x++) /* do every column */ 


{ 
latch = *(rgen) ; 
*(rgent+) = color ; 
} 
EGA_BIT_MASK(rght) ; /* Set the right bit mask */ 
latch = *(rgen) ; /* Latch the EGA bit planes */ 
*(rgent+) = color ; /* Set the color */ 
rgen += next_row ; /* Go to the next row */ 
} 
EGA_BIT_MASK(OxFF) ; /* Reset the Bit Mask */ 
EGA_GRFX(5,0) ; /* Reset the Write Mode */ 
} 


Write mode 2 is set with the macro EGA_GRFX(5,2). You must be careful not 
to send a value other than 0, 1, or 2 since the other bits of the byte sent to the 
mode register are significant to the EGA. The map-mask register and the bit- 
mask register are effective in write mode 2, but the set/reset register is not us- 
able. Write mode 0, the BIOS default write mode, is set with EGA_GRFX(5,0). The 
write mode must be reset to 0 before other programs or BIOS calls are used. 

Write mode 1 is used to copy one area of EGA memory to another area 
rapidly. This is most useful for scrolling, animation, or saving and restoring ar- 
eas of the screen. Write mode 1 allows you to copy the four bytes in each of the 
four bit planes with only one CPU read and write. The EGA memory offset con- 
taining the eight pixels to copy is read to prime the latch registers, then the off- 
set containing the destination for the eight pixels is written to by the CPU. When 
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the CPU writes a byte, and the write mode is set to 1, the EGA discards the byte 
from the CPU and copies the latch registers to each of the bit planes. Write mode 
1 is many times faster than reading the four individual bytes from the bit planes 
and then writing the four bytes back at the new address. The bit-mask register is 
not usable with write mode 1. All four bytes in the latch registers are written to 
all four bit planes regardless of the setting of the bit mask. The map-mask regis- 
ter can be used to protect individual bit planes. 

The next program, model1.c, demonstrates write mode 1. A pattern of lines 
is drawn at the top of the screen. That pattern is then copied using write mode 1. 
Finally, the edge of the pattern is redrawn rapidly to demonstrate the potential 
for animation. 


/* modei.c */ 

/* This program demonstrates EGA write mode 1 */ 
#define LINT_ARGS 

#include <conio.h> 

#include <dos.h> 

#include <stdio.h> 

#include "ega.h" 


void copy( int,int,int,int,int,int ) ; 


void main 
{ 
register i,j; 
int k = 0; 
set_crt_mode(16) ; /* Enhanced Monitor Only! */ 
/* Draw an interesting pattern: */ 
for(k = 0; k <= 4; ++k) 
for(j = O+k; j <= 5O00+k; j += 5) 
for¢i = Otk; i <= 100t+k; ++i) 
fastdot(i,i+j,13) ; 
for(k = 0; k <= 3; ++k) 
for(j = Otk; j <= SOO0+k; j += 5) 
for(i = O+k; i <= 100+k; ++i) 
fastdot(i,itj,3) ; 
/* Copy the pattern 120 rows down: */ 
copy (0,0,105,639, 120,0) ; 
while(!kbhitQ) 
{ 
/* copy the edge repeatedly, 
**x gives the illusion of motion: */ 
copy (99,100,106,592, 219,100) 
copy (99,100,106,592, 219,108) 
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} 
set_crt_mode(3) ; 


void copy(ri_1, c1_1, r2_1, c2_1, r1_2, c1_2) 
int r1_1, c1_1, /* Upper left corner of source */ 
r2_1, c2_i, /* Lower right corner of source */ 
rie, ¢l_2 3 /* Upper left corner of destination */ 
{ 
/* Copies one screen region to another rapidly. Uses 
** write mode 1. Only the upper corner of the destination 
** needs to be given. */ 
char far *source = (char far *)(OxAQOOQOOOL) ; 
char far *destination = (char far *)(OxAQOOOOCOOL) ; 
int rows = r2_1 - r1_1; 
int cols = (c2_1 >> 3) - (c1_1 >> 3) ; 
int bytes_per_line = GET_CRT_COLS() ; 
int next_row = bytes_per_line - cols ; 
register x,y 3; 


source += bytes_per_line * r1_1 + (c1_1 >> 3) ; 
destination += bytes_per_line * r1_2 + (c1_2 >> 3) ; 


EGA_GRFX(5,1) ; /* Set write mode 1 */ 
forfy = 0; y < rows ; y++) 
{ 


for(x = 0; x < cols; x++) 
*(destinationt++) = *(sourcet+) ; /* copy four bytes */ 
source += next_row ; 
destination += next_row ; 
} 
EGA_GRFX(5,0) ; /*x Reset the write mode */ 


Since the bit-mask register is not usable in write mode 1, the copy () routine 
will copy all eight pixels in the source bytes to the destination bytes. In other 
words, write mode 1 is only usable on bytes rather than pixels. Write mode 1 can 
be used to save an area of the screen to a nonvisible page, which is useful for 
implementing pull-down menus. The area under the pull-down menu can be 
saved to a nonvisible page, then restored after the user has finished with the 
menu. Write mode 1 can only copy to another part of the EGA’s memory. Reading 
a color from EGA memory requires reading the four bit maps individually. 
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Reading the Bit Maps 


Since each byte of address space in the EGA represents four bytes of graphics 
memory, EGA memory cannot be read by the CPU directly. The EGA will return 
the byte from the bit plane selected in the read map select register. The map to 
read must be set before reading the EGA offset containing the pixels you are 
interested in. Determining the color of a given pixel requires a separate read 
from each of the four bit planes. Each bit of the four-bit color value is on one of 
the four bit planes. The most significant bit of the color value is on bit map 3, and 
the least significant bit is on bit map 0. The read map select register is index 4 on 
the EGA’s Graphics ~ 1&2 chip. Since each of the EGAs bit maps must be read 
individually, the value in the read map select register corresponds to only one 
EGA bit map at a time. 

The function readdot returns the color of a pixel on the display. Like 
fastdot (), it is several times faster than the equivalent BIOS routine to read the 
color of a dot. 


/* return the color of a pixel */ 
int readdot (row, col) 
int row,col; 


{ 

register color = 0; 

register latch ; 

unsigned char far *rgen = (char far *)(OxAQOOOO0OL + 

(col >> 3) + 
(row * GET_CRT_COLS())) ; 

int bit_number = (col & 7)*7 ; 

int bit_mask = (1 << bit_number) ; 

int plane ; 

/* step through each plane 3,2,1,0 */ 

for(plane = 3; plane >= 0; plane--) 

{ 
EGA_GRFX(4,plane) ; /* select plane to read */ 
Latch = *(rgen) & bit_mask ; /* bit from that plane */ 
Latch >>= bit_number ; /* right justify the bit */ 
color <<= 1; /* make room for new bit */ 
color |= latch ; /* add the bit */ 

} 

return(color) ; 

} 


The offset of the byte containing the pixel is determined in exactly the same 
way as in the fastdot () routine. A value for a bit mask is calculated by determin- 
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ing the bit number of the byte to change. But the bit-mask value is not sent to the 
EGAs bit-mask register. The EGAs bit-mask register has no effect on bytes read 
from the EGA. The bit mask is used to isolate the pixel from the byte read from 
the EGA’ bit plane. The bits are then added plane by plane to the pixel’s color 
code. The read map select register selects the map to read from. The bit maps 
are read backward, (3, 2, 1, 0), since that makes the color code translation easier. 
Notice that the read map select register is not reset at the end of the routine. The 
last time through the loop sets the read map select register to 0, which is the 
default value. 


A Print Screen Routine with Dithering 


Although the readdot () routine could be used for a graphics print screen rou- 
tine, it would be very slow (over three minutes). The reason readdot () is so slow 
for multiple pixels is that each EGA byte is read 32 times to return the color of 
the eight pixels (8 pixels x 4 bit planes). A print screen routine can be made 
much faster by reading the EGA four bit planes only once and keeping the values 
in an array that can then be accessed much quicker. This technique is used in the 
print screen routine in the next listing. The print screen is written for a Hewlett- 
Packard LaserJet printer. Since the LaserJet cannot print colors, the prtsc() 
function uses an array of dither patterns, each unique to one of 16 colors. The 
array of dither patterns is indexed by the color of the pixel and the row the pixel 
is on. 


/*® prtsc.c */ 

/* This function will print a graphics screen to 

** an HP LaserJet Printer */ 

#include <dos.h> 

#include <string.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include "ega.h"' 

prtsc(res) 

int res ; 

{ 

/* The array contains 8x8 dither patterns for each EGA color */ 

static unsigned char dither(16][8] = 
{ 

{ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 +}, /* O «/ 
€ 0x88,0x44,0x22,0x11,0x88,0x44,0x22,0x11 }, /* 1 */ 
€ 0x88,0x11,0x22,0x44,0x88,0x11,0x22,0x44 }, /* 2 */ 
€ 0x18,0x24,0x42 ,0x81,0x18,0x24,0x42,0x81 }, /* 3 «/ 
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ANNO AAA AA AA A 


+; 
union REGS 


OxAA,0OxAA,0xAA,OxAA,OxAA,OxAA,OxAA,OxAA 
OxFF,Ox00,OxFF,0x00,0xFF,Ox00,0xFF,0x00 
0x88 ,0x00,0x22,0x00,0x88,0x00,0x22,0x00 
OxEE, OxFF,OxBB,OxFF,OxEE,OxFF,0xBB,OxFF 
OxAA,0x55,0xAA,0x55,0xAA,0x55,0xAA,0x55 
0x77 ,OxBB,OxDD,OxEE,0x77,0xBB,OxDD,OxEE 
0x77, OxEE,OxDD,0xBB, 0x77 ,OxEE,0x0D,0xBB 
OxE7 ,0x08 ,OxBD,0x7E,0xE7,0xDB,O0xBD ,Ox7E 
Oxcc,OxccC,OxCcC,Oxcc,Oxcc,OxCcC,0xcc,OxCcc 
OxFF,OxFF,0x00,0x00,0xFF,OxFF,0x00,0x00 
OxFF,Ox00,OxFF,Ox00,0xFF,OxFF,OxFF,Ox00 
OxFF,OxFF,OxFF,OxFF,OxFF,OxFF,OxFF,OxFF 


inregs, outregs ; 


int scan_lines = get_scan_lines( ; 


unsigned char far *rgen = (char far *) (OxAQOQQ000L) 


+ (PEEK_WORD(0x40,0x4C) 
* PEEK_BYTE(Ox40,0x62)) ; 


unsigned char bit_planes([4] ; 


static char start_raster_graphics(] = { "\x1B*rtA" } ; 
static char end_raster_graphics([] = { "\x1B*rB" > ; 


char transfer_graphicsl[7] ; 
char set_resolution[16] ; 
char buffer(7] ; 


char *cp ; 


int row, col, line, lLine_multiple ; 
char color, plane ; 

int bit_mask,byte,bit ; 

char crt_mode = PEEK_BYTE(0x40,0x49) ; /* CRT graphics mode */ 
int bytes_per_line = GET_CRT_COLS( ; 


if (crt_mode < 13) 


/* EGA modes only */ 


return(Q) ; 

if (crt_mode == 14) 

/* 640x200 mode, print each Line twice */ 
Line_multiple = 1 ; 


else 


Line_multiple 


nl 
oO 


strcepy(set_resolution,"\x1B*t") ; 
strcat(set_resolution,itoa(res,buffer,10)) ; 
strcat(set_resolution,"R") ; 

cp = strcat(set_resolution, start_raster_graphics) ; 


inregs.x.dx = 0; 


/* LPT1 */ 


/x 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


inregs.h.ah = O ; 
whileCinregs.h.al = *cp++) 
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/* Print character call */ 
/* Print the string */ 
int86(0x17,&inregs,&outregs) ; 


strepy (transfer_graphics,"\x1B*b") ; 
strceat (transfer_graphics,itoa(bytes_per_line,buffer,10)) ; 
strceat (transfer_graphics,"W") ; 


EGA_GRFX(3,24) ; 


/* Set the EGA to XOR «/ 


for Crow = 0; row < scan_lines; ++row) 
for (line = 0; Line <= lLine_multiple; ++line) 


{ 


cp = transfer_graphics ; /* Set the LaserJet for */ 
whileCinregs.h.al = *cp++) /x a line of graphics */ 


int86(0x17,&inregs,&outregs) ; 


for (col = 0; col < bytes_per_line; ++col) 


{ 


/* First, read the EGA bit planes. */ 
for(plane = 0; plane <= 3; ++plane) 
{ 
EGA_GRFX(4, plane) 
bit_planes[plane] 


fl se 


rgen[(col + row * bytes_per_line)] 


} 
/*x XOR the byte just read: */ 
ifCline || crt_mode != 14) 
rgen[(col + row * bytes_per_line)] = OxFF ; 


for (byte = 0, bit = 7; bit >= 0; --bit) 
{ 
bit_mask = 1 << bit ; 
/* calculate the color of ONE pixel masked by bit_mask: */ 
color = (((bit_planes(3] & bit_mask) >> bit) << 3) } 
(((bit_planes(2] & bit_mask) >> bit) << 2) | 
(((bit_planes{1] & bit_mask) >> bit) << 1) ! 
(((bit_planes([0] & bit_mask) >> bit) ) ; 
/*x Read a byte from dither based on the row and color: */ 
byte |= (dithe. [color]((row & 7)] & bit_mask ) ; 
} 
/* Print the bytes: */ 
inregs.h.al = (char)byte ; 
int86(0x17, &inregs, &outregs) ; 
/* Restore the previous row: */ 
if(Crow) && C!Line)) 
{ 
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byte = rgen((col + (row-1) * bytes_per_line)] ; 
rgen[{(col + Crow-1) * bytes_per_line)] = OxFF ; 


} 
cp = end_raster_graphics ; /* set the LaserJet for text */ 
while Cinregs.h.al = *cpt++) 

int86(Ox17,&inregs,&outregs) ; 


/* Restore the last Line: */ 
for(col = 0; col <= bytes_per_line; ++col) 


{ 
byte = rgen[(col + (row-1) * bytes_per_line)] ; 
rgen[(col + (row-1) * bytes_per_line)] = OxFF ; 
} 
EGA_GRFX(3,0) ; /* Reset the EGA */ 
return(1) ; 
} 
/ Meee eee Se eS SSS SS SS SSSSSSSSSSSSSSSer2eSSsSesssessssaaK / 
int get_scan_lines© 
{ 


int scan_lines ; 
switch(PEEK_BYTE(0x40,0x49)) /* video mode is at 40:45 */ 
{ 


case 13: 
case 14: scan_lines = 200 ; /* a 200 line mode */ 
break ; 
case 15: 
case 16: scan_lines = 350 ; /* a 350 line mode */ 
break ; 
default: scan_lines = 0 ; /* Unknown mode */ 
} 
return(scan_lines) ; 


} 


If you compile and run prtsc(), you will notice a line advancing from the 
top of the screen to the bottom, showing how much of the screen has been 
printed. This line is created by XORing the contents of all the EGA bit maps with 
OxFF. But how do you XOR all four bit maps without reading and storing each 
one? The answer is to use the EGAs data rotate register. This register allows the 
contents of the latch registers to be rotated, ANDed, ORed, or XORed with the 
data from the CPU. The meaning of each bit of the data rotate register is shown 
in Figure 12-3. 
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jee Rotation Count for Byte from the CPU 


Function Selection: 


BITS 

4 3 

0 O Data is unmodified 

0 1 CPU byte is ANDed with latch bytes 
1 0 CPU byte is ORed with latch bytes 
1 1 CPU byte is XORed with latch bytes 


Unused on the EGA 


Fig. 12-3. The data rotate register. 


Using the data rotate register to rotate the byte from the CPU is of limited 
use. The latch registers are not rotated by this function, only the CPU data. The 
CPU is just as able to rotate the byte before sending it. However, the AND, OR, 
and XOR functions are very useful for quick logical operations on the bytes in 
the latch registers. 

The stream I/O functions from the C library (such as fprintf() or fputs() 
are not used in prtsc() because any byte (0 — OxFF) may be sent to the printer as 
graphics data. Some values, such as EOF (0x1A), have special meaning to MS 
DOS. If the prtsc() routine tried to send 0x1A to the printer using one of the 
stream I/O functions, MS-DOS would terminate I/O rather than printing the 
byte. Even opening the device for binary output will not cure this. To get around 
this problem, each byte is printed directly using the PC BIOS print character call 
INT 0x16. 

If you do not have a LaserJet printer, you should be able to adapt the 
prtsc() function to another printer easily. The main thing to change is the 
printer control strings. The other potential change is the method used to send 
graphics data to the printer. The LaserJet, and most other new printers, take 
graphics one horizontal line at a time. Older printers may need graphics sent in 
8x8 chunks. As an example, here is an equivalent print screen for an Epson 
printer: 


#include <dos.h> 

#include <string.h> 

#include <stdio.h> 

Hinclude <stdlib.h> 

#include "ega.h" 

prtsc() 

/* This print screen is for an Epson FX-80 */ 
{ 
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static unsigned char dither(161][8] = 
{ 

0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 
0x88 ,0x44,0x22,0x11,0x88,0x44,0x22,0x11 
0x88 , 0x11 ,0x22,0x44,0x88,0x11,0x22,0x44 
0x18,0x24,0x42,0x81,0x18,0x24,0x42,0x81 
OxAA,OxAA,0xAA,0xAA,0xAA,OxAA,OxAA,OXAA 
OxFF,Ox00,0xFF,0x00,0xFF,0x00,0xFF,0x00 
0x88 ,0x00 ,0x22,0x00,0x88,0x00,0x22,0x00 
OxEE,OxFF,OxBB,OxFF,OxEE,OxFF,OxBB,OxFF 
OxAA,0x55,0xAA,0x55 ,OxAA,0x55,0xAA,0x55 
0x77 ,0xBB,Ox0D,0xEE,0x77,0xBB,0xDD,OxEE 
0x77, OxEE,0x00,0xBB,0x77 ,OxEE,Ox00,0xBB 
OxE7 ,Ox0B ,OxBD,0x7E,0xE7,0xDB,OxBD,0x7E 
Oxcc,Oxcc,OxCcC,Oxcc ,OxcC ,OxcC,Oxcc,Oxcc 
OxFF,OxFF,0x00,0x00,0xFF,OxFF,0x00,0x00 
OxFF,Ox00,OxFF,Ox00,OxFF,OxFF,OxFF,0x00 
OxFF,OxFF,OxFF,OxFF,OxFF,OxFF,OxFF,OXxFF 


Aa Aa AA AA AA A AAA A A 


+; 
union REGS inregs, outregs ; 
int scan_lines ; 
unsigned char far *rgen = (char far *) (OxAQOOO0000L) 
+ (PEEK_WORD(0x40,0x4C) 
* PEEK_WORD(O0x40,0x62)) ; 
unsigned char bit_planes([4] ; 


CON OU KF WN = © 


= -3-= £0 
- Oo 


=> = = os 
uw SW PS 


static char start_raster_graphics{] = { "\xD\xA\x1b\x33\x18" 


+; 

char transfer_graphics(7] ; 
char *cp ; 

int row, col, line_multiple ; 
char color, plane ; 

int bit_mask,byte,bit ; 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
«/ 
*/ 
*/ 
*/ 
«/ 
«/ 
*/ 


char crt_mode = PEEK_BYTE(0x40,0x49) ; /* CRT graphics mode */ 


int bytes_per_line = GET_CRT_COLSQ) ; 
int ni, n2; 


if (crt_mode < 13) 
return(Q) ; 
switch(crt_mode) 


/* EGA modes only */ 


{ 

case 13: lLine_multiple = 2 ; 
scan_lines = 200 ; 
break ; 

case 14: Line_multiple = 4 ; 


466 


Chapter 12: Enhanced Graphics Adapter 


scan_lines = 200 ; 


break ; 

case 15: 

case 16: line_multiple = 2 ; 
scan_lines = 350 ; 
/* falls through! */ 

} 


cp = start_raster_graphics ; 
inregs.x.dx =0; /* LPT1 */ 


inregs.h.ah = 0; 
whileCinregs.h.al = *cp++) 


/* Print character */ 
/* Print the string */ 
int86(0x17,&inregs,&outregs) ; 


strepy (transfer_graphics,"\xOD\xOA\x1B\x4c"") ; 
n2 = (line_multiple * scan_lines) / 256 ; 

ni = (line_multiple * scan_lines) - n2 * 256 ; 
transfer_graphics[4] = (char)n1 ; 
transfer_graphics[5] = (char)n2 ; 
transfer_graphics[6] = (char)O ; 


EGA_GRFX(3,24) ; /* Set the EGA to XOR */ 


for (col = 0; col < bytes_per_line; ++col) 


{ 


cp = transfer_graphics ; 


whileCinregs.h.al = *cp++) 


/*x Print the string */ 
int86(0x17,&inregs,&outregs) ; 


for Crow = scan_lines - 1; row >= 0; --row) 


{ 


/* First, read the EGA bit planes. */ 
for(plane = 0; plane <= 3; ++plane) 
{ 
EGA_GRFX(4,plane) 
bit_planes[plane] 
} 
/* XOR the byte just read: */ 
rgen{(col + row * bytes_per_line)] = OxFF ; 


{1 we 


rgen((col + row * bytes_per_line)] 


for (byte = 0, bit = 7; bit >= 0; --bit) 
{ 
bit_mask = 1 << bit ; 
/* the color of ONE pixel masked by bit_mask: */ 
color = (((bit_planes(3] & bit_mask) >> bit) << 3) ! 
(((bit_planes[2] & bit_mask) >> bit) << 2) !} 


e 
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(C(bit_planes(1] & bit_mask) >> bit) << 1) } 
(((bit_planes[0] & bit_mask) >> bit) ) ; 
/* byte from dither based on the row and color: */ 
byte j= (dither(color]((row & 7)] & bit_mask ) ; 
} 
/* Print the byte: */ 
for(n1 = 1; n1 <= line_multiple; ++n1) 


{ 
inregs.h.al = byte ; 
int86(0x17,&inregs,&outregs) ; 
} 
if€col != Q) 
{ 
byte = rgen[(col-1 + row * bytes_per_line)] ; 
rgen((col-1 + row * bytes_per_line)] = OxFF ; 
} 
} 
} 
for (row = scan_lines - 1 ; row >= 0; --row) 
{ 
byte = rgen[(col - 1 + row * bytes_per_line)] ; 
rgen[(col - 1 + row * bytes_per_line)) = OxFF ; 
} 
EGA_GRFX(3,0) ; /* Reset the EGA */ 
return(1) ; 
} 


A print screen generated from the color bar program (rect.c) is shown in 
Figure 12-4. This print screen took about 16 seconds to print with a parallel 
LaserJet, printed with Prtsc.c. Each color is shown dithered. 


EGA Color Palettes 


When used with an Enhanced Color Monitor, the EGA can display any 16 colors 
from a 64-color palette. It takes four bits to represent 16 colors. Each of these 
bits corresponds to one of the EGAs four bit planes. On the CGA, and with the 
EGAs default palette, the four bits correspond to red, green, blue, and intensity 
(IRGB). But once the EGA palette is changed from the default, the four-bit color 
code is simply an index to the new palette. 

The 64-color palette has the same three basic colors (red, green, blue) as 
the 16-color palette, but there is no intensity bit. Instead, each color has two bits 
for individual intensity, giving three intensity levels for each color. The total 64- 
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Fig. 12-4. Color bar print screen. 


color palette may be represented with six bits. The bits for the lower intensity of 
the three colors are the most significant bits in the six-bit value, and are usually 
abbreviated as lowercase rgb for red, green, and blue. The least significant three 
bits are the brighter red, green, and blue and are abbreviated as RGB. The total 
six-bit value, rgbRGB, is used to select one of the 64 colors. Once one of the 16 
colors is set to an rgbRGB value, that color may be selected with a four-bit IRGB 
value. The bits of an rgbRGB value will always indicate the red, green, and blue 
components of the resulting color, but an IRGB value is simply an index to the 
current palette. 

The RGB colors can only be used with an EGA connected to an Enhanced 
Color Monitor. When the EGA is connected to a Color Display, only the 16 colors 
from the default palette may be used. In text modes and the EGA graphics 
modes, individual palette registers may be set to any of the 16 default colors. In 
the CGA compatible modes, the palette must be changed using the CGA compati- 
ble BIOS calls. 

The EGA also has an overscan register. The color value sent to the overscan 
register is displayed as a border. However, the overscan is usable only in the 200 
scan line modes. 


EGA BIOS Routine: Set Palette (NT 0x10) 


The EGA’ palette registers are most often set with a new EGA BIOS call. The 
BIOS call can set either one of the 16 colors, or all 16 at once. The BIOS call is 
Function 0x10 of Interrupt 0x10. There are four subfunctions: 0 sets individual 
palette registers to any rgbRGB value (or any IRGB value if the EGA is not con- 
nected to an ECD); 1 sets the overscan register; 2 sets all the palette registers and 
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the overscan register; and 4 toggles between text blinking and intensity. The sub- 
function is selected in register AL. 


Call with: AH 0x10 

AL = 0, Set Individual Palette Register 
BL = color number (RGB) to change 
BH = rgbRGB value to set 


AL = 1, Set Overscan Register 
BH = color number to set 


AL = 2, Set All Palette Registers and Overscan 
ES:DX points to a 17-byte table 
Bytes O—15 has the 16 rgbRGB values for colors 0O—15 


Byte 16 is a color number for the Overscan Register 


AL = 3, Toggle Intensity/Blinking Bit 
Changes the meaning of bit 7 of the text attribute 
byte. 

BL = 0, allow background intensity 

BL = 1,allow foreground blinking 


Unfortunately, the palette registers are write-only. It is not normally possi- 
ble to determine what rgbRGB value a given color number represents. The EGA 
BIOS will check for the existence of a 256-byte table called the parameter save 
area when changing the palette registers. The BIOS will save the rgbRGB values 
in that table if it exists. The creation and maintenance of a parameter save area 
will not be covered here, but it is important to use BIOS calls to set the palette so 
that a parameter table will be updated. 

The following is a program that demonstrates the uses of the palette regis- 
ters. It will only work with an EGA/ECD combination. The program will first 
draw 16 colored rectangles using the rect () function. The palette is then contin- 
uously changed. 


/* palette.c */ 
/* demonstrates the 64 color palette */ 
#define LINT_ARGS 
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#include <conio.h> 
#include <dos.h> 
#include <stdio.h> 
#Hinclude "ega.h"' 


void set_all_pal(char *) ; 
void gotoxXYCint,int) ; 


main() 

{ 

int i,j,ch = QO; 

char palette[17)]] ; /* This array holds the palette */ 
set_crt_mode(16) ; /* Make sure you 


xx have the right monitor! */ 


/* Draw some color bars: */ 
printf('\nColor #z\n') ; 
for (i=0, j=0;1<163;++i, j+=40) 


{ 
printf’ 421i ",i);3 
rect (50, j,300, j+39,i); /* from Listing 5 */ 
paletteli] = (char)i; /x initialize the array */ 
} 


gotoxY(15,22) ; 

printf('"rgbRGB of color 7") ; 

printt ("%ctcachchcdc",205,205,205,205,205,190) ; 
gotoxY(20,0) ; 

printf("Press Space to single space, Esc to exit'') ; 


palette[16] = (char)O ; 


while(ch != 27) /* while not ESC */ 
{ 
if (kbhit()) /* If a key is hit, */ 
ch = getch() ; /* get the character */ 
for (i = 13 i1<=15; ++i) 
{ 
palettelij++; 


if (paletteli) == 64) /* max rgbRGB value */ 
palette(rlJi] = 1 ; 
} 
set_all_pal(palette) ; /* Set the palette */ 
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gotoxY(15,23) ; 


/* Convert the rgbRGB value to binary: */ 


fordi = 53;1>=0; --i) 
if(palettel[7] & 1<<i) 
putchar('1') ; 
else 
putchar('O') ; 
if (ch == 32) 
whileC!kbhit()); 


set_crt_mode(3) ; 


void set_all_pal(palette) 
char *palette ; 


/*x single space mode */ 


/* This function sets the entire palette */ 


{ 
union REGS regs ; /* 
struct SREGS segregs ; /* 


the 8086 registers */ 


the 8086 segment registers */ 


char far *fp = (char far *)palette ; 


regs.h.ah = 0x10 ; /* 
regs.h.al = 2 ; /* 
segregs.es = FP_SEG(fp) ; /* 


EGA BIOS call set palettex/ 
Function to set all */ 

ES to segment of palette */ 
DX to offset of palette */ 


set cursor function */ 
page 0 */ 

row */ 

col */ 

call int Ox10 */ 


regs.x.dx = FP_OFF(fp) ; /* 
int86x(Ox10, S&regs, &regs, &segregs) ; 
} 
/ RSSSSSSSSSSSSSSSSeSeSsessassseee= 
void gotoxy (x,y) 
int x,y 3 
/* This function moves the text cursor to x,y */ 
{ 
union REGS regs ; 
regs.h.ah = 2 ; /* 
regs.h.bh = 0 ; /* 
regs.h.dh = (chandy ; /* 
regs.h.dl = (char)x ; /* 
int86(0x10, &regs, &regs) ; /* 
} 
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Making Everything Faster 
Remember the macros EGA_GRFX and EGA_S@NC? They are reproduced here: 


#define EGA_GRFXCindex, value) { outp(Ox3ce, index) ; \ 
outp(Ox3cf, value) ; 
H#define EGA_SQNCCindex, value) { outp(Ox3c4, index) ; \ 
outp(Ox3c5, value) ; 


Each of these macros sends an index to one of the EGA’ ports followed by a byte 
of data. EGA_GRFX sends the index to Ox3CE and the data byte to Ox3CF EGA_SQNC 
sends the index to 0x3C4 and the data byte to 0x3C5. In both cases, the address 
of the index port is one port below the data port. You can take advantage of this 
arrangement to make every code listing that uses these macros up to 30 percent 
faster. The key is to output a word (two bytes) to the lower of the two addresses, 
rather than a byte to each address. 

Borland’s Turbo C already has the library function to output a word to a 
port. It is called outport (). The macros only need to be slightly rewritten to take 
advantage of outport (). Since Turbo C already produces much faster code than 
the Microsoft compiler, the speed improvement is not dramatic. However, the 
change is easy to make, and does increase the speed of the example programs 
about 10 percent. 

The Microsoft C library only includes the function outp(), and will only 


send a byte at a time. To send a word requires writing a new function in assem- 
bly: 


; out.asm 
; does word outs with the Microsoft Compiler 
: This example is for the small model only 


assemble with : MASM out /ML 

Link with your program with: LINK yours.obj out.obj 
The /ML makes lower case labels 

ret_sequence equ 4 


=e =e fe 


_TEXT segment byte public ‘CODE’ ; use the Microsoft segments 
assume cs:_TEXT 


public _outport this is called 


=e 


_outport proc near ; small model uses near calls 
push bp s save the stack frame 
mov bp, sp 3 point to the arguments 
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add bp, ret_sequence : skip over the return 


mov dx, (Cbp] 
mov ax, [bp+2] 


the port 
the data to send 


me =e %e Ge we 


out dx, ax send the data 
pop bp recover the stack frame 
ret 


_outport endp 


_TEXT ends 
end 


The word output function is named outport() to provide compatibility 
with Turbo C. When word outs are done, the byte in AL is first written to the 
port number in DX, and then the byte in AH is written to the port DX + 1. That 
means the data byte must be the byte in AH, and the index byte needs to be in 
AL. The macros are rewritten like this: 


H#define EGA_GRFXCindex, value) \ 

outport (Ox3ce, ((Cint)value << 8) | Cindex)) ) 
#define EGA_SQNCCindex, value) \ 

outport (0x3c4, ((Cint)value << 8) | Cindex)) ) 


Conclusion 
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With the EGA, everything is complicated. IBM was locked in to supporting two 
very different previous display standards (the CGA and MDA) when designing 
the EGA. The result now is supported in the even more complicated VGA. Your 
best bet for designing software to run on the EGA without sacrificing future 
compatibility is to separate hardware-dependent code into logically independent 
functions. For example, the fastdot() routine should be easy to rewrite for all 
future IBM displays. A more complicated plotting routine that calls fastdot © to 
plot dots would not need to be rewritten as long as fastdot () supports the dis- 
play. Also consider how easy it was to upgrade all the routines in this paper sim- 
ply by rewriting the EGA_GRFX and EGA_SQNC macros. Now every routine is faster 
since they all can do word outs rather than byte outs. 

This essay has developed several basic graphics functions: lineQ, 
fastdot(), readdot (), prtsc(), and rect (). Many of the EGA peculiarities, such 
as latch registers, have been examined. The three ways of setting a color on the 
EGA, the map-mask register, the set/reset register, and write mode 2, have also 
been shown. Although the routines in this paper are fast, there are many im- 
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provements that could be made. High performance graphics routines on the 
EGA tend to be found only though exploration. 
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Essay Synopsis: Most MS-DOS com-  - 
puters these days need to use serial commu- 
nications to transfer messages, programs, 
and data with other computers. Since many 
applications programs require serial com- 
munications capability, these functions be- 
long in every programmer's toolkit. This 
essay begins by covering the basic concepts 
of asynchronous serial communication, in- 


cluding a discussion of error-detection 


methods and common communications pro- 
tocols. This is followed by a look at the ac-. 
tual serial port hardware and how it can be 
used to control modems, to manage XON/ 
XOFF flow control, and to handle interrupts. 
Finally, the author presents a complete inter- 
rupt-driven, buffered serial communications | 
package implemented in Microsoft C. 
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Programming the Serial 
Port with C 


Nabajyoti Barkakati 


The PC and data communications are rapidly becoming an integral part of our 
lives. PC users routinely expect to be able to share programs, send messages and 
use their PCs to talk to other computers, large and small. An increasing number 
of computers are now hooked up in networks and various protocols and stan- 
dards have been developed to guarantee that all computers in a network can 
communicate with each other and even with other networks. If you develop ap- 
plications for the PC, chances are that you will one day be required to exploit its 
communications capabilities. 

Luckily for us, enough standardization exists in the PC arena to allow us to 
write a single software package to handle most communications chores. To sum- 
marize in a single jargon-laden sentence: In the PC world, we normally commu- 
nicate by asynchronous serial data transfers using the ASCII encoded character 
set and Universal Asynchronous Receiver Transmitter (UART) based hardware 
connected to a telephone line via an RS-232-C port and a modem. If all of these 
terms are too technical for you, don’t despair—we will explain each and guide 
you through the design and implementation of a small but very functional serial 
communications package written in C. 


Basics of Asynchronous Data Communications 


Textual information is stored in computers by representing each character by a 
pattern of bits as prescribed by the ASCII code (ANSI standard X3.4-1977). The 
code uses seven bits per character, stored in the rightmost seven bits of an eight- 
bit byte. The ASCII code provides for 128 characters, which allows us to repre- 
sent all upper- and lowercase letters, the numerals, and the punctuation sym- 
bols. In addition, there are 32 nonprintable characters (control characters) that 
are often used to signal special conditions—carriage return, line feed, form feed, 
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etc. Two of these characters, Control-S and Control-Q, are used in what is known 
as the XON/XOFF flow control during asynchronous communications. 

In data communications, we are interested in transferring the bytes from 
one device to another, e.g., from the PC to an electronic Bulletin Board System 
(BBS). If we had eight lines between the two points, we could let each line corre- 
spond to a bit and send the data one byte at a time. This would be a parallel 
transfer. The parallel port on the PC works this way, though in addition to the 
eight data lines there are other signals to assist in the data transmission. On the 
other hand, if we have only a single line, we would send each byte of data serially, 
one bit at a time. In addition to these options, we may also decide to send the data 
synchronously so that every byte is sent at a predetermined time (e.g., once every 
x seconds), or asynchronously at a rate that is not necessarily uniform. Serial 
communications is cheaper than parallel because it requires only one data line. 
Also, the asynchronous mode of transmission makes much less demand on 
hardware because there is no need for special hardware to maintain synchro- 
nism between the transmitter and the receiver. Thus, asynchronous serial com- 
munications is the preferred solution. Of course, in this mode of data 
transmission we must have a means to convert each data byte into a series of bits 
and indicate to the receiver the beginning and the end of each byte. Figure 13-1 
illustrates the concept of asynchronous serial communication. 

For the moment, let us assume that we have some means of converting each 
byte into a stream of 1s and 0s, bits that can be transmitted over the communica- 
tions medium (for example, the telephone line). In fact, the UART performs pre- 
cisely this function, as we will see in the next section. It is normal practice to 
indicate that a line is “okay” by keeping it at a logical 1 when it is idle. In this case, 
the line is said to be marking. On the other hand, when the line is at a logical 0, it 
is said to be spacing. Thus, logical 1 and 0 are also referred to as MARK and 
SPACE respectively. In asynchronous communications, a change in the condition 
of the line from MARK to SPACE indicates the start of a character (see Figure 
13-2). This is referred to as the START bit. A pattern of bits follows the START bit, 
representing the character and a bit known as the PARITY bit. Finally, the line 
transitions to its idling MARK condition which represents the STOP bit and indi- 
cates the end of the current character. The number of bits used to represent the 
character is known as the wordlength and is usually either seven or eight. The 
PARITY bit is used to perform rudimentary error detection. 

How does the transmitter (or the receiver) know how long each bit lasts? In 
fact, both must have some knowledge of this duration or the detection of the bits 
would be impossible. The duration of each bit is determined by data clocks at 
the receiver and the transmitter. Note, however, that while the clocks at the re- 
ceiver and the transmitter must have the same frequency, they are not required 
to be synchronized. The selection of the clock frequency depends on the baud 
rate, which essentially refers to the number of times the line changes state every 
second. Nominally, a clock rate of 16 x baud rate is used so that the line is sam- 
pled often enough to detect a bit reliably. 


A single byte is reconstructed 
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Fig. 13-1. Asynchronous serial communications. 


In addition to the ASCII characters used for information exchange, there is 
one particular condition of the line that is sometimes used to gain the attention 
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Fig. 13-2. Format of a single character. 


of the receiver. Remember, the normal state of the line is MARK (1) and the be- 
ginning of a character is indicated by a transition to SPACE (0). If the line stays in 
the SPACE condition for a period longer than the time it would have taken to 
receive all the bits of a character, we say that a BREAK condition has occurred. 
There is no ASCII representation of BREAK—it is essentially the line “dropping 
dead” for a short duration of time that constitutes a BREAK. 


Parity and Error Detection 


Earlier, we mentioned the PARITY bit as being useful for error detection. For 
example, when even parity is selected, this bit is set so the total number in the 
current word is even. (A similar logic applies for odd parity.) At the receiving end, 
the parity is recalculated and compared with the received parity bit. If they disa- 
gree, the receiver declares that a parity error has occurred. A major drawback 
of error detection via parity check is that it can only detect errors that affect a 
single bit. For example, the bit pattern 0100 0001 0 (ASCII A, with a 0, or even 
parity bit) transmitted with eight-bit wordlength and even parity may change 
(due to say, noise in the line) to 0100 0111 0 (ASCII G), but to the receiver, every- 
thing would seem fine because there is still an even number of ones. 

A much more reliable scheme of detecting errors is the so-called Cyclic Re- 
dundancy Check (CRC). Instead of checking errors in a single character, the CRC 
checks for errors in a block of characters. As shown in Figure 13-3, the CRC 
calculation treats a block of characters as a single binary number (with a large 
number of bits!) and finds a 16-bit remainder after dividing this number by a 
prespecified 17-bit divisor, for example, the CCITT polynomial: 


X® +X? + X> +1 
Since the remainder after a division is always less than the divisor, by choosing a 
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17-bit divisor we are guaranteed, at most, 16 bits in the remainder. The remain- 
der is known as the CRC checkvalue and often referred to as the CRC of that 
block. The two-byte CRC checkvalue is then sent at the end of the block of char- 
acters and, at the receiver, the CRC is recalculated and compared with the re- 
ceived CRC to check for transmission errors. Thus, each block of characters 
would have two more bytes appended and these would be the CRC (or the Block 
Check) characters. How good is this method of error detection? Research has 
shown that the CRC can detect a burst of errors shorter than 16 bits with 100 
percent accuracy. CRC is widely used in hard disks for error detection. File 
transfer protocols such as XMODEM and KERMIT also use CRC. 


Biock of characters 


1 0001 ©c000 0010 0001 0100 1101 0101 0011 0100 0100 0100 1111 0101 0011 


—_—_—_—_e[vw='__—-—-—xvl--—’ eee (quotient is discarded) 
17-bit divisor 


16-bit remainder ——~ XXXX XXXX XXXX XXXX 
a a, 
ane 


or CRC checkvalue 
appended to message block 


Fig. 13-3. Computing the CRC bytes. 


Since a detailed discussion of this topic is beyond the scope of this essay, we 
refer the reader to chapter 3 of Campbell (1987) and chapter 13 of McNamara 
(1982). Both authors provide a thorough analysis of several CRC techniques and, 
more importantly, present algorithms to compute CRCs. 

So far we have talked about sending and receiving individual characters. 
The serial communications package that we will develop operates at this level. 
However, there are other higher-level protocols (or conventions) used when 
transmitting files from one computer to another that send data in the form of 
packets of characters with additional information to help the receiver answer 
such questions as 
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=> Was the packet received without errors? 
= How do I construct the original file out of the received packets? 


= How do I decode the information in case it is encoded? 


The two most widely used file transfer protocols in the PC world are 
XMODEM and KERMIT. Once again, we are taking the easy way out by referring 
the reader to books that describe these protocols. The recent book by da Cruz 
(1987), who was one of the original authors of the KERMIT protocol, has a very 
complete discussion of KERMIT. The XMODEM protocol, originated by Ward 
Christensen in 1977, is also discussed (pp. 303-309). Campbell (1987) also de- 
scribes both of these protocols. 


Communicating with the RS-232-C Standard 


Although in the PC we represent the 1s and Os by voltage levels, the signals car- 
ried in a telephone line are usually tones of different frequencies. The device 
that sits between the PC’s hardware and the transmission line, and makes data 
communication possible, is the modem (modulator/demodulator). A modem can 
convert information back and forth between the voltage/no voltage representa- 
tion of digital circuits and analog signals (for example, tones) appropriate for 
transmission through the telephone lines. Standards such as the RS-232-C, set 
forth by the Electrical Industry Association (EIA), specify a prescribed method 
of information interchange between the modem or data communications equip- 
ment (DCE), and the PC’s communications hardware or data terminal equipment 
(DTE). A modem can be operated in one of two modes: half duplex or full duplex. 
Half duplex mode can only transmit in one direction at a time while full duplex 
operation permits independent two-way communications. The RS-232-C stan- 
dard provides control signals such as Request To Send (RTS) and Clear To Send 
(CTS) that may be used to coordinate the transmission and reception of data. As 
shown in Figure 13-4, the RS-232-C standard is evident in the cable and connec- 
tors used to connect the PC to the modem. The arrows in the figure point to 
equipment for which the signal is intended. Table 13-1 lists the acronyms and 
their meanings. 
Various other configurations of the cables are shown in Campbell (1987). 


Flow Control with XON/XOFF 


In addition to the “handshaking” via the hardware RTS/CTS signals, special AS- 
CII control characters (Control-O/Control-S or XON/XOFF) are used to achieve 
flow control in software. Flow control is necessary because sometimes either the 
transmitter or the receiver may not be able to keep up with the rate of transmis- 
sion and should be able to inform the other party to stop while it catches up. 
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Table 13-1. RS-232-C Signals 
a 


Acronym Meaning 
eee 

TD Transmitted Data 

RD Received Data 

RTS Request To Send 

CTS Clear To Send 

DSR Data Set Ready 

RLSD Receive Line Signal Detector 

DTR Data Terminal Ready 


To 
telephone 
line 


PC or Data 

Terminal Equipment 

(DTE) 
Modem or 
Data Communication Equipment 
(DCE) 


Fig. 13-4. The RS-232-C connection. 


Suppose the receiver has a buffer to store incoming characters. As the buffer 
gets close to full, the receiver can send an XOFF character to the transmitter to 
indicate that transmission should stop. Of course, the transmitter must under- 
stand the meaning of XOFF and cease sending characters. Then when the re- 
ceiver processes characters (e.g., puts them in a disk file) and the buffer empties, 
it can send an XON to indicate that transmission can proceed. This scheme of 
flow control is widely used because of its simplicity. In the serial communica- 
tions package we will develop, we will be primarily concerned with full duplex 
communication with XON/XOFF flow control. 

Now that we have gone over some of the basics of asynchronous serial com- 
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munications, let us roll up our sleeves and see how we can program the PC's 
communications hardware. 


Taming the UART 
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The most common communications hardware on the IBM PC and compatibles is 
the serial or asynchronous communications adapter or serial adapter. This 
adapter is based on the Intel 8250 UART, has an RS-232-C port for connecting to 
the communication channel (for example, the telephone line) via a modem, and, 
like the graphics adapter, is programmable through a set of registers. The regis- 
ters are accessible from the 8086 or 80286 microprocessor in the IBM PC 
through predefined I/O port addresses. Note that the information presented in 
this section is, of necessity, somewhat technical. However, everything will fall 
into place once you go through the C code presented later and correlate it with 
the material in this section. 

The Intel 8250 UART is controlled by writing to or reading from a set of 
internal data locations called registers. Each register can hold a byte. These reg- 
isters are accessible to the programmer via port addresses. The port addresses 
are assigned sequentially, so it is enough to know the address of the first port to 
be able to find any other. This is also commonly known as the base address of the 
serial adapter. In the IBM PC, the two serial ports COM1 and COM2 are assigned 
base port addresses 3F8h and 2F8h respectively. Thus for the serial adapter 
COM1, the first register is at 3F8h, the next one at 3F9h and so on. 

There are seven physical registers in the 8250 which we will investigate in 
the order of increasing offsets from the base address (see Figure 13-5). At the 
base port address, there is a single register which doubles as the receive buffer 
register and the transmit holding register used to store a single character that is 
received or is being transmitted. Next comes the interrupt enable register which 
is used to enable, by setting the bit to 1, or disable interrupts that the serial 
adapter is capable of generating. The third register, the interrupt identification 
register, contains the UART’s report on the identity of an interrupt. In the 3-bit 
interrupt ID (bits 0-2), 110 means line status, 100 means received data, 010 means 
transmit buffer empty, and 000 means modem status. Then comes the line con- 
trol register used to set up various communications parameters such as word- 
length, number of stop bits, parity, and baud rate. In bit 6, 1 sets the line to 
SPACE. (See Essay 5, Advanced MASM Techniques, by Michael Goldman, for ex- 
amples showing how to manipulate these bits in assembly language.) The fifth 
register is the modem control register, which is used to send signals such as DTR 
and RTS to the modem. Bit 3 must be 1 for interrupt I/O on PC. Finally, the last 
two registers, the line status register and the modem status register indicate the 
status of the line and the modem, respectively. 
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Fig. 13-5. Registers in the 8250 UART. 


Base Address +3 


Base Address + 4 


cee 
Base Address +5 


Base Address +6 


The first two registers are also used in setting baud rates, but for the sake 
of brevity, we will skip over some of these details, focusing our attention on only 
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those aspects of programming the serial adapter that have a direct bearing on 
our goal—to develop a serial communications package for the PC. 


Interrupts vs. Polling 


As you might already know, there are two common methods of I/O in any com- 
puter system: polled and interrupt-driven. In polled I/O, the program requesting 
the character repeatedly reads a status register in the I/O device until it indicates 
that a character is available for input (or until the program decides to “time out’). 
When the status indicates that there is a character ready, the program reads the 
character from the appropriate register in the I/O device. A similar sequence of 
“wait until ready, then write” is used when writing characters out to the I/O de- 
vice. Thus, the thread of execution of the program is held up until the I/O opera- 
tion is complete. The polling refers to the repeated checking of the status 
register of the I/O device to see if the desired transaction can be initiated. A big 
problem with polled I/O through the communication port is that, at baud rates 
above 300 baud, there is hardly any time available for the program to do any- 
thing with the received character, even display it on the screen. Consider the 
following example. Suppose you are reading characters at 300 baud and the 
communication parameters are seven-bit wordlength, even parity, and one stop 
bit, which with the start bit adds up to 10 bits per character. So you expect to 
receive roughly 30 characters every second. After reading a character, your pro- 
gram has about ‘4cth of a second to do other chores. If you do not want to miss 
any characters you must begin polling the port again before this time is up. 
What happens when the speed is increased to 9600 baud? You guessed it! The 
time interval between characters is too short to even put the received character 
up on the display let alone interpret special characters and emulate a terminal. 

In the interrupt-driven approach, the program enables interrupts from the 
/O device, assuming it is capable of signaling interrupts to the CPU, and then 
goes about its own business without any concern about the device. Whenever 
the device is ready for I/O, it signals the CPU via hardware. Upon receiving this 
signal, the CPU saves its current state and invokes an interrupt service routine 
whose address is stored in an interrupt vector table. This routine performs the I/ 
O and then restores the state of the machine and returns control to the CPU. 
Consider the case of characters arriving at the communication port of the PC. If 
you set aside some memory locations to hold characters {a buffer), you can use a 
simple interrupt handling routine that quickly reads the character from the 
communication port and saves it in the next available location in the buffer. As 
long as the interrupt handler can read and save a character before another one 
arrives, no characters will be lost. This simple task is easy enough to complete 
even in the short time interval between characters at 9600 baud. The beauty of 
this method is that it does not matter how long the main program takes to ma- 
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nipulate the characters saved in-the buffer. Of course, there is the risk of filling 
up the buffer, but this can be remedied by simply increasing the size of the 
buffer. If this is not good enough, there is XON/XOFF flow control to help us out. 

From our discussion, it is clear that an interrupt-driven, buffered commu- 
nication package with XON/XOFF flow control is preferred over a polled imple- 
mentation, so we will develop an interrupt service routine that will, depending 
on the cause of the interrupt, either read a character from the adapter and save 
it in a receive queue or send out a character from a transmit queue. That way, our 
main program (which may be a terminal emulator) can feed itself off the receive 
queue and send out characters by simply placing them in the transmit queue. 
How are interrupts enabled and and how are they serviced? Let's explore the 
possibilities. 


Servicing Interrupts from the Serial Adapter 


The serial adapter on the PC can be programmed to interrupt the CPU when- 
ever one of four things happens (see Figure 13-6). The UART assigns a priority to 
each of these events. Table 13-2 lists the four interrupts. 


ASCII Characters 


123 4 
interrupt 
enable reg. 
Interrupt 
identification 
Serial 
Adapter 


Interrupt 
to 8259A 


Fig. 13-6. Interrupts from the serial adapter. 


The event with highest priority is the receive line status (RLS) interrupt. 
This occurs when one of the following happens: the line goes dead (logical 0) for 
a period longer than that necessary to receive a character, a character is re- 
ceived before the last one was read (an overrun error), there is a parity error, or 
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Table 13-2. Serial Adapter Interrupts 


re 


Priority Interrupt ID 

1 Receive line status (RLS) 

2 Receive data available (RDA) 

3 Transmit holding register empty (THRE) 
4 Modem status (MS) 


oh ESS SS Se 900 0000S 


no stop bit was found while assembling a character out of the received bits (a 
framing error). This interrupt is processed by reading the line status register. 

Next comes the receive data available (RDA) interrupt that occurs when a 
character is ready in the receive buffer register. It can be cleared by reading the 
character from that register. Of course, in our scheme of things, the character 
will be squirreled away into a receive queue. 

The transmit holding register empty (THRE) interrupt has the next priority. 
As the name suggests, it occurs when the register assigned to hold the character 
to be transmitted (same port address as the receive buffer register) is empty. 
This interrupt is processed by writing into this register or by reading from the 
interrupt identification register. The second method of clearing this interrupt is 
necessary because sometimes, even though the UART interrupts to say the 
transmit buffer is empty, there may not be anything to transmit. 

The lowest priority interrupt is the modem status (MS) interrupt, and is 
caused when the modem 


asserts (sends) the CTS signal 
-- indicates its readiness by setting the DSR line 
receives a call, in which case the RI line becomes a logical 1 


detects a carrier signal (the tone you hear when you dial a number and a 
modem answers), which means the RLSD line is set to 1 


This interrupt can be cleared by reading the modem status register. 

Each of these interrupts may be turned on or off individually by setting 
appropriate bits in the interrupt enable register. On the IBM Serial/Parallel 
Adapter (as well as the IBM Asynchronous Adapter) the bit named OUT2 in the 
modem control register must also be set to 1 before interrupts from the UART 
can reach the CPU. When interrupts occur, the serial adapter arranges them 
according to priority and indicates the pending interrupt of highest priority in 
the interrupt identification register. The adapter stops responding to further in- 
terrupts of equal or lower priority until it determines that the current one has 
been serviced by the interrupt service routine. 
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8259A: The CPU's Receptionist 


In the IBM PC (and compatibles) the CPU does not directly accept interrupts 
from hardware devices such as the serial adapter. Rather, hardware interrupts 
are first fielded by an Intel 8259A Programmable Interrupt Controller (PIC) chip. 
The 8259A acts as the CPU’s “receptionist” A programmable device, the 8259A 
accepts up to eight distinct interrupts and can mask (i.e., ignore) interrupts indi- 
vidually. The 8259A responds to each unmasked or allowed interrupt and for- 
wards it to the CPU, provided no other interrupt of higher priority is being 
serviced at that moment. 

How does the 8259A assign priorities? Just as the UART has its method of 
determining priorities of interrupts generated from the serial adapter, the 
8259A also has its own scheme of assigning priorities to interrupts. The serial 
adapter is only one of several hardware devices that can interrupt the 8259A. 
Each device is hardwired or jumpered into distinct inputs known as interrupt 
request (IRQ) inputs in the 8259A. That's why it is customary to talk about the 
IRQ assigned to a hardware interrupt. Another feature is also tied to the IRO of 
an interrupt—the interrupt number used in referring to that particular inter- 
rupt. On the IBM PC, this number is eight plus the IRQ. This is the number used 
by the CPU when looking up the address of the interrupt handling routine from 
the interrupt vector table. Since the 8259A associates higher priorities with 
lower IRQs, the hardware devices needing maximum attention have lower IRQ. 
Thus the system timer gets IRQO, the keyboard has IRQ1 and so on. The two 
communication ports COM1 and COM2 are respectively assigned IRQ4 and 
IRQ3, resulting in interrupt numbers 12 and 11 (decimal). By the way, the inter- 
rupt numbers must be known so that DOS function call (software Interrupt 21h) 
with Function numbers 35h and 25h can be used for get and set interrupt vec- 
tors, respectively. (See Essay 5, Advanced MASM Techniques, by Michael Gold- 
man, for a discussion on avoiding pitfalls in interrupt handling.) 

A few more details to note: The CPU automatically disables all interrupts 
when it transfers control to the actual software service routine for the current 
interrupt. So unless we do something, while we are processing a character from 
the serial port, the system timer, the keyboard and the disk will not be serviced. 
Since many vital system functions rely on interrupts (for example, updating of 
the system time), it is important to turn interrupts back on as soon as the service 
routine gets control—with an STI SeT Interrupt flaginstruction. Although dur- 
ing the servicing of an interrupt the 8259A inhibits further interrupts of the 
same or lower priority, higher priority interrupts are still acknowledged, and if 
the interrupt flag is set, our serial service routine will be interrupted. This will 
then allow the timer, the keyboard, and the disk to interrupt our routine, al- 
lowing them to function properly. 

How do we tell the 8259A when the serial interrupt processing is complete? 
Our service routine has to send an end-of-interrupt E01 command to the 8259A 
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before returning control to the CPU. Although there are ways of indicating an 
end-of-interrupt for a specific IRQ, for the priority scheme used in the PC it is 
enough to send what is known as a nonspecific end-of-interrupt (code 20h) to 
the 8259A, nonspecific because it does not specify which interrupt has been 
serviced but simply tells the 8259A that the servicing is complete for the highest- 
priority interrupt that has been acknowledged. This reenables acknowledgment 
of further interrupts at that IRO or lower. 


Programming the 8259A 


How do we program the 8259A? As with any hardware in the PC, the 8259A is 
programmed via two command words (registers) at I/O port addresses 20h and 
21h, respectively (see Figure 13-7). The register at 21h is used solely for masking 
interrupts. An interrupt is masked (i.e., not acknowledged) if the bit correspond- 
ing to its IRQ (counting from right to left with the rightmost bit assigned to IRQO) 
is a logical 1. The port at 20h is used to send the end-of-interrupt command to 
the 8259A. As we noted earlier, on the PC this is done by writing 20h to this port. 

Various programming tricks follow from this scheme of things. The first 
serial port in the IBM PC (known as COM1: to MS-DOS) is assigned IRQ4 (Inter- 
rupt number 12), and the second one (COM2:) has IRQ3 (Interrupt 11). Thus, the 
8259A can be programmed to acknowledge interrupts from COM1: by reading 
from the port at 21h and writing back the contents logically ANDed with EFh. 
Interrupts from COM1: may be masked by repeating the above step but ORing 
with 10h in place of the logical AND. Programming devices in this manner, by 
first reading the contents of a register and then writing back again with the ap- 
propriate bit altered, is recommended because that way we do not disturb any 


. prior bit settings. 


Sorry, We Don’t Do Much BIOS 


After being swamped by all this information, you are probably wondering if we 
could do all these via the BIOS? Unfortunately, the answer is no. Unlike the mini- 
mal support for the graphics adapter, the BIOS provides hardly anything in the 
way of controlling the serial adapter for us. The BIOS does have a function, Inter- 
rupt 14h, to access the serial adapter. Unfortunately, this function only supports 
polled I/O which is not much help because of the drawbacks of polling we have 
outlined earlier. However, this function is ideal for the initial setting up of the 
parameters of the communication port, and we will make use of this function in 
our package to save code. Another useful built-in feature of the BIOS is that dur- 
ing the Power On Self Test (POST) phase, it checks for the existence of serial 
adapters COM1 and COM2 and if it finds either, the address of the first register 
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-Fig. 13-7. The 8259A programmable interrupt controller. 


of each adapter is stored in an area of memory beginning at offset zero of seg- 
ment 40h. Since, in the PC, a 20-bit physical address equals 10h x 16-bit segment 
+ 16-bit offset, if your PC has a single serial adapter designated as COM1:, the 
physical location 400h would contain 3F 8h. So in our interrupt-driven package, 
we will get the port address of the serial adapter from this BIOS data area at 
offset 0 and segment 40h. 

We need to go over just a few more details before we can design the com- 
munications package. The serial adapter in the PC supports full duplex commu- 
nication (that means, we can transmit and receive simultaneously) with the 
following programmable parameters. Using BIOS Interrupt 14h, the baud rate 
can be set to 110, 150, 300, 600, 1200, 2400, 4800, or 9600 baud. The parity can be 
one of none, odd, or even, but the line control register may be directly pro- 
grammed for space or mark parity as well. Either one or two stop bits are al- 
lowed and the wordlength can be seven or eight bits. 
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Queues for the Interrupt Handler 


We have mentioned the use of buffers to save received characters. Conceptually, 
the buffer should behave like a checkout line at the supermarket cash register. 
The incoming characters line up one after another and the program reading the 
characters takes the first one in the line and processes it, then takes the next, 
and so on. This type of buffer is known as First In First Out or FIFO buffers. 
They are also called queues. 

Figure 13-8 shows the conceptual realization of a queue. The queue natu- 
rally has a front and a rear. In an actual implementation, the queue size, i.e., the 
maximum number of characters it can hold, is fixed. It is convenient to think of 
the storage locations assigned to the queue as a circle so that once we go past the 
last location we come back to the first one again. This makes efficient use of the 
limited space available in the queue, and is called circular implementation. 
Tremblay and Sorenson (1984, 217-23) describe algorithms to implement a circu- 
lar queue. 


Fig. 13-8. A circular FIFO buffer (queue). 


Summary 


Programming the serial adapter for interrupt-driven I/O requires that we do the 
following: 
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1. Get the base port address of the selected communication port from BIOS 
data area at segment 40h and offset 0. 


2. Using MS-DOS Function, 35h, get the address of the old interrupt service 
routine for the interrupt number corresponding to this adapter and save 
it. 


3. Using MS-DOS Function 25h, install our own interrupt service routine 
for that interrupt number. 


4. Set up the communication parameters of the adapter using BIOS Func- 
tion 14h. 


On 


. Set up the receive and transmit queues to hold incoming and outgoing 
characters. 


6. Turn on signals needed by modem (e.g., DTR and RTS in the modem con- 
trol register). 


7. Enable all interrupts from the adapter (by setting bits 0 through 3 of the 
interrupt enable register to 1). 


8. Turn on the bit OUT2 in the modem control register to enable interrupts 
from the serial adapter. 


9. Program the 8259A to recognize interrupts with the IRQ of this adapter 
(by setting the appropriate bit to zero in the interrupt mask register ac- 
cessed through the port address 21h). 


At some point, when the user decides to terminate the communication ses- 
sion, a “cleanup” routine should be called involving the following steps: 


. Turn off interrupts from the serial adapter. 

. Reset the bits in the modem control register. 

. Restore the old interrupt service routine. 

. Mask the interrupts for this IRQ in the 8259A. 


& WwW bw 


Specifications for Our Serial Communications 
Package 


Based on what we know so far, the specifications for our serial communication 
package are fairly simple. We want to be able to perform interrupt-driven, buff- 
ered I/O from the serial communications adapter configured as either COM1 or 
COM2. We need one buffer to store received characters and another one for 
characters waiting to be transmitted. The buffers ensure that the interrupt han- 
dler has some place to save characters and return control to other processing as 
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quickly as possible. In case the buffer should fill up, we want to allow XON/XOFF 
flow control. As we mentioned earlier, many installations respond only when a 
BREAK signal is received so our software must be able to send a BREAK. This 
requires that the line be held in a spacing state for a period longer than the time 
it takes to send all the bits of a character at the current baud rate. (Generally, 250 
milliseconds is long enough.) The user should be able to set communications 
parameters such as baud rate, wordlength, number of stop bits and parity easily. 
Some computers often play games with the unused eighth bit in a byte repre- 
senting a character. For example, one might set the eighth bit to 1, another might 
require that this bit be always 0. In order to be able to keep up with these incon- 
sistencies, the software should have the ability to selectively turn the eighth bit 
of each byte to 1 or to 0 while transmitting or receiving. In order to test the 
package, we also need a main routine. We will go over the major pieces one by 
one. You may find it convenient to consult the listings at the end of this essay as 
we go through the design. 

Since there will be a lot of reference to the listings, Tables 13-3 through 13-6 
show the sequence in which they appear and a short description of the func- 
tions contained in Listings 13-2 through 13-5. (There is no table for Listing 13-1, 
Makefile for Microsoft MAKE, because it is short.) 


Table 13-3. Listing 13-2: Main Program COMTEST.C 


Function Description 

main() Main routine to test package 

connect() Connects over serial line as a dumb terminal 

sendfile() Sends file to serial port 

newparams() Changes communications parameters 

showparams() Displays current settings of communications parameters 


Table 13-4, Listing 13-3: Assembly Language Portion of Package 


Function Description 


—_s__saveds Saves current contents of DS register in a location in its code segment, in- 
voked from C as s_saveds(). 

_s_inthndlr Interrupt handler for serial port, calls s_mainhndlr () in Listing 13-5. 

—s_cli Disables interrupts 

—_S_Ssti Enables interrupts 


The main program in Listing 13-2 shows typical usage of the functions in 
our communications package. Listing 13-1 has the makefile that can be used 
with Microsoft’s MAKE to prepare the executable version of the test program 
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COMTEST. The package itself consists of some assembly language routines shown 
in Listing 13-3, the C routines in Listing 13-4 that provide the capability to buffer 
characters, and the C routines in Listing 13-5 to handle interrupts and perform 
setup and cleanup operations. 


s__setcommparams() 


s —_setvals() 
s_vtblsrch() 
s__getvals() 

s —sendchar() 
s _revehar() 
s__txqempty() 
s__sendbreak() 
s —delay() 


Table 13-5. Listing 13-4: The Circular Buffer (Queue) Package 
Function Description 
q—setup() Allocates storage and initializes circular queue 
q—reset() Deallocates queue 
q—getfrom() Returns next element in queue 
q—puton() Inserts new element into queue 
Table 13-6. Listing 13-5: C Portion of Package, SERIAL.C 
Function Description 
s__mainhndlr() Handles interrupts from PC's serial port 
s_rls() Handles receive line status interrupt 
s_rda() Handles receive data available interrupt 
s_trmty() Handles transmit holding register empty interrupt 
s_ms() Handles modem status interrupt 
s_setup() Sets up serial port and the 8259A for interrupt-driven I/O 
s _intinit() Enables interrupts from serial port 
s_cleanup() Cleans up before exiting to DOS by disabling interrupts from se- 
rial port and restoring old interrupt vector 
s_intoff() Disables interrupts from serial port 


Sets up communications parameters of serial port using BIOS 
Function 14h 

Internal utility routine to set new value for a parameter 
Routine to search internal table for a string 

Returns string containing value of a parameter 

Places character on transmit queue 

Returns character from receive queue 

Returns 1 if transmit queue is empty 

Sends BREAK signal 

A coarse timer used by s_sendbreak () 


Overview 


Figure 13-9 shows a flow chart for the program COMTEST.C (Listing 13-2). This 
program is provided so you can test the serial communications package. The 
main program accepts optional command line arguments specifying communi- 
cations parameters such as baud rate, parity, port number, etc. First it goes over 
these arguments and calls the function s_setvals() to enter the name of each 
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Fig. 1 3-9. 
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parameter and its value into an internal table maintained in the file SERIAL.C 
(Listing 13-5). This table is used to translate the value of each parameter entered 
by the user into an internal form. For example, this allows us to enter the string 
“even” as the value of the parameter named parity even though internally “even 
parity” is denoted by the integer 3. The internal forms are dictated by what BIOS 
accepts, but we see no reason to burden the user with these details. So, 
s_setvals() essentially hides the details and makes it easy for us to enter new 
values for the parameters. 

After processing the command-line arguments, the program enters an end- 
less loop to accept single character commands and process them until it receives 
the command q. You can get a list of the commands by typing h. (Commands can 
be entered in either lower- or uppercase, and are converted to uppercase.) A ? 
displays the current parameter settings by calling the function showparams () to 
do this. New communication parameters can be entered by typing p. The C func- 
tion newparams() will prompt you for the names and the values of the parame- 
ters you want to change. Two commands follow that are more interesting 
because they actually perform serial communications. 

The s command calls the function sendfile( to transmit a file over the 
serial port. If you happen to have your printer hooked up to the serial port, you 
can use this function to print files. This can be very handy because most printers 
with a serial interface require the use of XON/XOFF flow control but the PRINT 
command under MS-DOS does not use XON/XOFF. In other words, using this 
function as a model, you can write your print utility for printers hooked up to 
the PC's serial port. 

The last and most interesting command is c that calls the C function con- 
nect () which emulates a “dumb” terminal. This is the typical way a package like 
this might be used. The following is a detailed description of how connect () 
works. 

First, the communication port is set up by the routine s_setup(. This gets 
the address of the serial port from the BIOS data area in segment 40h and sets up 
various masks for enabling and disabling interrupts from the serial adapter. It 
uses DOS Function 35h to get and save the address of the current interrupt han- 
dler for serial interrupts, following which it installs our package's interrupt han- 
dler s_inthndlr() using the DOS function call with Function 25h. Then it calls 
the routine s_setcommparams() which uses the RS232 interrupt (14h) of the BIOS 
to set the communication parameters. Next the value of the DS register is saved 
by calling s_saveds() (Listing 13-3). This is a crucial step because, as you will see, 
our interrupt handler calls a C routine to do the actual work. All important vari- 
ables are in the C function's data segment. That is why we must save the value of 
DS in the assembly code so that data is accessible during interrupt handling. 
After this step, memory is allocated for the transmit and the receive queues and 
some internal variables are initialized to default values. Finally, interrupts are 
enabled by calling s_intinit. 

After setting up the serial port, connect () falls into an endless loop that 
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first calls s_rcvchar( which returns a character if there are any in the receive 
queue or returns a 1 otherwise. If a character is returned, it is simply displayed 
and the keyboard is checked for any unprocessed keystrokes. If there are none, 
the routine returns to the beginning of the loop. If a character is found waiting 
in the keyboard buffer, it is read. As long as this character does not match a 
predefined special character (DEFAULT_ESC in the listing), the character is placed 
on the transmit queue by calling the routine s_sendchar() from the package, 
and then the loop is repeated. 

Why is there a predefined special character? It allows us to exit from the 
endless loop and provides a way to send a BREAK signal. If a match with the 
special character is found, the routine waits for one more character, and if that 
character is a qit exits after performing the necessary cleanup functions by call- 
ing the routine s_cleanup(). If it is a b, a BREAK signal is sent by calling 
s_sendbreak(). 

The routine s_cleanup() is used to reset everything at the end of a commu- 
nication session. This routine calls s_intoff() to turn off all interrupts from the 
serial adapter and mask the interrupt at the 8259A. Then the original interrupt 
vector for the serial interrupt is restored. Finally, the storage allocated to the 
transmit and receive queues is released. 

How is the BREAK signal sent? The routine s_sendbreak () first puts the line 
in a spacing state by setting bit 6 of the line control register (LCR) to a logical 1. 
The BIOS time-of-day interrupt (number 1Ah) is used to achieve a delay of ap- 
proximately 250 milliseconds, at the end of which bit 6 of LCR is reset to logical 
0. This delay is achieved by calling the C routine s_delay() (Listing 13-5). 

The other two routines we mentioned, s_sendchar() and s_revchar(), are 
high-level interfaces to the communications package. Using these routines, you 
can place characters in and retrieve characters from the transmit and the re- 
ceive queues. 

How are the characters magically appearing in the receive queue and disap- 
pearing from the transmit queue? All this is happening behind the scenes cour- 
tesy of our friendly interrupt handler that was duly installed as the guardian of 
the serial port when s_setup( was called. 


FIFO Buffers 


For buffered I/O, there must be some FIFO buffers set up to hold incoming and 
outgoing characters while they are waiting to be processed. As described ear- 
lier, we have chosen to implement a circular queue. Listing 13-4 shows @PAC.c— 
an implementation of a generic circular FIFO buffer. The routine q_setup() is 
used to allocate memory for a queue and initialize some internal variables such 
as front and rear indices of the queue. Notice that the number of elements in the 
queue and the size of each element are selected by the programmer by passing 
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them as parameters when calling q_setup(). The queue is deallocated by 
q_reset(). 

Of course, there must be a way to put elements on the queue and retrieve 
the first element in the queue. These functions are performed by the routines 
q_puton(® and q_getfrom(), respectively. 


Serial Interrupt Handler 


Now let us jump right into the heart of the package—the interrupt service rou- 
tine for the serial adapter. In the previous sections, we outlined the actions that 
should be performed by this interrupt service routine. It should first turn on 
interrupts (with an STI instruction) and save the current state of the machine (by 
pushing all the registers onto the stack), then read the interrupt identification 
register of the 8250 UART to determine which one of four events caused the 
interrupt. Next, it should perform the action necessary to clear the interrupt. If 
it is either a line status interrupt or a modem status interrupt, the handler sim- 
ply reads the line or the modem status register. If there is received data available, 
the handler reads the character from the UART'’s receive buffer and inserts it 
into the receive queue. If the interrupt indicates that the transmit holding regis- 
ter is empty and if the transmit queue is not empty, a character is retrieved and 
written out to the transmit holding register. After the processing is complete, an 
EOI (20h) should be sent to the 8259A and the registers should be restored. Then 
the routine should return by using an IRET (return from interrupt) instruction. 
(This is one reason why we must have some assembly language routines in our 
package.) Remember, an IRETinstruction is necessary to return from interrupts. 

The C routine s_mainhndltr() (serial main handler) services the interrupts 
from the serial port by calling one of the routines: s_rls( for line status inter- 
rupt, s_rda() for receive data available, s_trmty() when the transmit holding 
register is empty, and s_ms() for modem status changes. Figure 13-10 is a flow 
chart for the complete interrupt handler. 

The installed interrupt handler in our package is the assembly language 
routine s_inthndlr() shown in Listing 13-3. Immediately after saving the regis- 
ters, this routine calls s_mainhndtr() in SERIAL. C (Listing 13-5) which services the 
interrupt as outlined above. There is only one tricky part in this arrangement. 
The compiled version of the C routines in SERIAL.C will use the segment register 
DS to point to the area in memory where the variables and data are stored. At 
the time when the interrupt from the serial port occurs, there is no certainty 
that the DS register contains a value appropriate for the routines in SERIAL.C. We 
call this the problem of “establishing the addressability of the data” This prob- 
lem can be solved by saving the value of the DS register (appropriate for the 
routines in file SERIAL.c) at a location in the code segment of the assembly lan- 
guage routine during the setup (i.e., when s_setup() is called). From then on, 
whenever the assembly language routine s_inthnd|r() gets called because of an 
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Fig. 13-10. Flow chart of interrupt handler. 


interrupt, the 80X86 microprocessor will load the CS register with the code seg- 
ment of this routine and the saved value will always be accessible for loading the 
DS register before calling the C routine s_mainhndir(). Specifically, we call the 
assembly language routine s_saveds() (Listing 13-3) from the C routine 
s_setup() (Listing 13-5) during setup. This is the routine that saves the DS regis- 
ter (corresponding to the segment address of the data in the file SERIAL.Cc) ina 
location in the code segment of the assembly language routine. 

Notice that in s_mainhndlr(), interrupts are processed until no further in- 
terrupts are pending. This ensures that interrupts from the serial adapter, that 
may have occurred while an earlier interrupt was processed, don’t get lost. 

There are two more assembly language routines in the file SERASM.ASM. 
These routines, s_sti() and s_cli(), are used to set and clear the interrupt flag, 
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respectively. It is necessary to disable interrupts in some parts of the serial pack- 
age. For example, suppose you are installing an interrupt handler for the serial 
port. This means you are inserting the segment and the offset address of your 
routine into the CPU's interrupt vector table. What if an interrupt from the serial 
port should occur just after you've changed the segment address in the vector 
table, but before the offset is altered? With the CPU jumping off to this indeter- 
minate address, the results could be unpredictable and most likely, very unwel- 
come. So it is important to disable all interrupts during these crucial periods. 


Our Package and Microsoit C 


One of our goals was to implement as much of the communications package as 
possible in Microsoft C (we used version 4.0). As you can see by examining the 
listings, this is quite possible. Assembly language routines are only needed to 
perform the functions return from interrupt and set/clear interrupt flag be- 
cause Microsoft C has no functions to do these. We make use of the Microsoft C 
library functions inp and outp() to read from and write to port addresses. 
The communications parameters are set up by accessing BIOS via the function 
int86(). Similarly, DOS functions are accessed through intdosx(). The DOS 
functions are used to get (Function number 35h) and install (Function 25h) inter- 
rupt vectors. 

A note on memory models available in Microsoft C. The “large” memory 
model in the Microsoft C compiler uses full 32-bit (16-bit segment and 16-bit off- 
set) data and code pointers. This makes it slow compared to, for example, the 
“small” model which assumes that everything fits into two physical segments— 
one for code and one for the data. The large model has the benefit of allowing 
truly large-scale programs. To keep things simple, we have used the large model. 
Since the package works at 9600 baud with this model, it should also work with 
the small memory model. To change to the small model, you will have to replace 
the keyword Farin the assembly language routines with the keyword NEAR. Also, 
in the makefile (Listing 13-1), the line MODEL=L should be replaced with MODEL=s 
before reconstructing the executable. Other variations such as “mixed” memory 
models are also possible, but we will not consider them here. 

Our serial communications package and this essay were prepared prior to 
the release of version 5.0 of the Microsoft C compiler. Prerelease announce- 
ments and “beta test” reports indicate that the run-time library will be expanded 
considerably in version 5.0 with the inclusion of many new routines, most nota- 
bly in the categories of graphics, memory allocation, and MS-DOS/BIOS inter- 
face. Among the new routines for interfacing with the hardware are ones that 
can enable and disable 80X86 interrupts. There will also be a new attribute 
(named interrupt) for functions that tells the compiler to treat the function as an 
interrupt handler. This will instruct the compiler to use a “return from inter- 
rupt” instead of a “return from subroutine call’ as the last instruction in the com- 
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piled code. With these new features, it should be possible to write the serial 
communications package entirely in Microsoft C 5.0 with no need for routines 
written in Assembler. 


Testing the Package 


Listings 13-3, 13-4, and 13-5 constitute our serial communications package. Use 
the makefile ComMTEST in Listing 13-1 to prepare the executable COMTEST.EXE. 

The routines were compiled with Microsoft C 4.0 using the large memory 
model and tested on an IBM PC AT (PC-DOS 3.1) with an IBM Serial/Parallel 
Adapter. The dumb terminal was used at 9600 baud to communicate with a VAX/ 
VMS system without any problem. COMTEST also successfully printed files at 9600 
baud on an Imagen laser printer using XON/XOFF flow control. 


Conclusion 


Our serial communications package supports interrupt-driven, buffered I/O 
through the serial port, and may be used in application programs such as termi- 
nal emulators, file transfer utilities, and smart interfaces for minis and main- 
frames. The way it relies on a minimal amount of assembly language 
programming and uses C routines to service the interrupts could serve as an ex- 
ample if you want to develop C-based interrupt handlers. The information pre- 
sented in this essay may serve as a reference guide to those who are interested in 
developing other interrupt-driven applications, especially those involving asyn- 
chronous communications. 

Of course there is much room for improvement in the package. One obvi- 
ous function we can add is an XMODEM file transfer protocol with CRC error- 
checking, but we will have to save that for another time. 

The routines have been tested at speeds of 1200 through 9600 baud and 
found to work properly. However, the testing was far from thorough, so you may 
very well find some bugs. If you do, feel free to fix them and drop us a line. 


Program Listings and the Makefile 
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Listing 13-1. Makefile for Microsoft MAKE 


RAARAHHHRRRRARRRHRRAARRRRRARRRRRARAAHRRRRARRARARRARRHRARRARARRARAR 
# 
continued 
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Files COMTEST 


Makefile for COMTEST.EXE--a program to test an asynchronous 
communications package for IBM PC and compatibles. 


Copyright © 1987 Nabajyoti Barkakati 
Copies may be made for noncommercial, private purposes only. 


Ze Be Fe Be Ae BW BW FW 


HHHHRAHHHHHHARHARRARARHHARRRAHRHAAHHHRRHH RAR RARRRRARARRRARRRRAR ARAB 


MODEL=L 

SRC=. 

INC=. 

CFLAGS=-AS(MODEL) -ISCINC) -Gs -0Od 

# modelsize incl. nostkchk noopt. 


MSC=msc $C(CFLAGS) 
ASM=masm 


# General inference rules 
# Rule to make .OBJ files from .C files 


.C.OBJ: 
S(MSC) $*.C,,,3 


~-ASM.OBJ: 
SCASM) $*.ASM,,,; 


# Make object files 


COMTEST.OBJ: S(SRC)\COMTEST.C 


SERIAL.OBJ: SC(SRC)\SERIAL.C 


QPAC.OBJ: SC(SRC)\QPAC.C 


SERASM.OBJ: $(SCR)\SERASM.ASM 


# Make the executable 
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503 


Section 3: Working with the Hardware Interface 


504 


COMTEST.EXE: $(SRC)\COMTEST.OBJ SCSRC)\SERIAL.OBJ SC(SRC)\QPAC.OBJ\ 
$ (SRC) \SERASM.OBJ 

LINK Sxx, $a; 

ERASE $(SRC)\*.LST 

ERASE $(SRC)\*.COD 


RHRHHHHHRHHHRRHRRAH End of File: COMTEST ###HARAHRHRARRARHRAAAARAR 


Listing 13-2. Main Program, COMTEST.C 


| enn nn rere eee en nn on nn nn on nn nn ew = = = *x/ 
/* 

* Filename: COMTEST.C 

* Purpose: Test an asynchronous communication package for 

* IBM PC and compatibles. 

* This version was developed on an IBM PC-AT with 

* an IBM Serial Card. DOS version 3.1 was used. 

* Language: Microsoft C 4.0 

* Usage: Use makefile COMTEST with Microsoft MAKE. 

* 

* Sample invocation: 

* "'comtest baud 9600 parity none wordlength 8 stopbits 1'' 

* 

* When you run COMTEST.EXE you can set the 

* communication parameters, send a file over 

* the communication Line, and connect to the 

* serial port as a "dumb" terminal. 

* 

* Copyright © 1987 Nabajyoti Barkakati 


* Copies may be made for noncommercial, private purposes only. 


Date Started: 10-JAN-1987 
Revisions: V1.00 9-FEB-1987 -- First working version. (NB) 


#include <stdio.h> 
#include <conio.h> 
Hinclude <ctype.h> 


#define TRUE 1 
Hdefine FALSE 0 
#define BUFSIZE 512 
continued 
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#define CONTROL(x) (x-0x40) 
#define DEFAULT_ESC CONTROL(')') 


extern int s_setup(), s_sendchar(), s_rcvchar(), s_setvals(, 
s_cleanup(), s_txqempty(); 

extern void s_sendbreak(); 

extern char *s_getvalsQ; 


static char buffer(BUFSIZE); 


static char helplist(] = 
"\n\ 

-- exit.\n\ 

-- connect to serial port.\n\ 

-- send a file over serial port.\n\ 
show status. \n\ 
-- set new communication parameters.\n\ 
-- print this List.\n"; 


zs>u v waa 
t 
t 


mainCargc, argv) 


int argc; 
char *argvl]; 
{ 


static void connect(), newparams(), sendfileQ), showparams(); 
int ch, i, code; 

printf('\nCOMTEST 1.0 -- Testing Serial Communications\n"); 
printf(''Type H for help, ? for parameters.\n"); 


/* Setup communication port. Use parameters specified by user 

* on command Line, if any. Sample invocation: 

* comtest baud 9600 parity none wordlength 8 stopbits 1 

*/ 

if (argc > 1) { 
for (i = 1; i < argc; i += 2) { 
if (s_setvals(argvli], argvli+1]) == 0) ¢ 
fprintf(stderr, 

"Error setting parameter: %s to value: %s\n"', 
argvli], argvlit+1]); 


} 
/* Accept and respond to user command */ 
continued 
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while (TRUE) { 
printf('\nCOMTEST> "'); 
ch = getche(); 
code = toupper(ch); 
switch (code) { 
case ‘'Q': exit(0); 
case ‘C's: connect(); 


break; 
case 'S': sendfile(); 
break; 
case 'P': newparams(); 
break; 
case '?': showparams(); 
break; 
case 'H'’: printfChelplist); 
} 
} 
} 
[ kre nr es 5 - - - - = *x/ 


/* connect 
* Connect over serial port as a dumb terminal. 
*/ 
static void connect () 
{ 
int ch, nxt; 
printf(''\nConnecting...\n'"); 

/* First set up the serial port */ 
s_setupQ); 

/* The following endless loop simulates a very dumb terminal. 
* We first get a character from the receive queue, print it, 
* then check if any keystrokes are waiting. If a key was 
* struck, it's read in and sent out to the transmit buffer. 
* This sequence of steps is repeated until user hits the 
* 4] (CTRL and ]) keys together)--then a 'b' sends out 
* a BREAK signal and a ‘q' cleans up everything and returns. 


while (TRUE) ¢ 
if (ch = s_revchar()) != -1) putch(ch); 
if ( kbhit© != 0) { 
ch = getch(); 
if (ch == DEFAULT_ESC) { 
printf('\n'b' to send BREAK, ‘q' to quit\n'); 
nxt = getchO;if (nxt == ‘b’ |} mxt == 'B') 
continued 
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s_sendbreak(); 


} 
if (nxt == ‘'q’ |] nxt == 'Q') € 
s_cleanup(); 
return; 
} 
} 
else { 
s_sendchar (ch); 
} 
} /* End of kbhit() check */ 
+ 
} 
| 8 nn ww rn wr no nn rn nn nn no ne ee = = x/ 


/* sendfile 
* Send a file over the serial port. 
*/ 
static void sendfile( 
{ 
register int i, j3 
int readcount; 
unsigned long bytecount; 
char filename([40); 
FILE *xinfile; 


printf('\nEnter name of file to be transmitted: '"); 
scanf("%s"", filename); 
/* Open file for binary read only */ 
if (Cinfile = fopen(filename, "rb')) == NULL) ¢ 
fprintf(stderr, "Error opening file: %s\n", filename); 
return; 
} 
printf("Transmitting file...\n'; 
/* First set up the communications port */ 
s_setupQ; 
bytecount = 0; 
j = 0; 
while (TRUE) { 
/* Read in a "chunk" from the file into a buffer */ 
readcount = fread(buffer, sizeof(char), BUFSIZE, infile); 
bytecount += readcount; 
for (i=0; i < readcount; i++) { 
/* Keep sending each character until successful */ 
continued 


507 


Section 3: Working with the Hardware Interface 


while ((s_sendchar(bufferlil)) != 1); 


} 
j++; 
if (j == 10) € 
j = 0; 
printf¢"Zlu", bytecount); 
} 
else { 
putch('.'); 
} 


if Creadcount < BUFSIZE) { 
printf ("Cend)\nTransmitted 4lu characters.\n", 


bytecount); 
/* Now wait until the transmit queue is emptied out */ 
while (s_txqempty© != TRUE); 
/* Close comm port and return */ 
s_cleanupQ; 
return; 


/‘* newparams 
* Set new parameters in the communications package. 
*/ 
static void newparams() 
{ 
int ch; 
char pname(20], pvalue[20); 
while (TRUE) ¢ 
printf('\nParameter name (Q to quit): "); 
scanf(''%s", pname); 
ch = pname[0); 
if (toupper(ch) == 'Q') return; 
printf("Change %s from %s to: ", pname, 
s_getvals(pname)); 
scanf("%s", pvalue); 
if (s_setvals(pname, pvalue) == 0) { 
fprintf( stderr, 
"Error setting parameter: %s to value: %s\n", 
pname, pvalue); 


continued 
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else { 
printf("'%s is now %s\n", pname, pvalue); 
} 
} 
} 
[| Be nn nn nn nn nnn nn ne nen ne = x/ 
/x* showparams 
* Show current parameters. 
*/ 
static void showparams() 
{ 
printf("\n Current Settings\n'); 
printf(' Name Value\n'"'); 
printf("port = %s\n", s_getvals("port'")); 
printf ("baud = s\n", s_getvals('baud') ); 
printf (''wordlength = 4s\n", s_getvals("wordlength'")); 
printf("stopbits = Z%s\n"', s_getvals("stopbits')); 
printf("parity = %s\n", s_getvals("parity")); 
printf (''xonxoff = %s\n", s_getvals("xonxoff")); 
printf("null_ignore = %s\n'"', s_getvals("null_ignore')); 
printf('"del_ignore = %s\n'"", s_getvals("del_ignore")); 
printf("8thbitO_on_rx = &s\n"', s_getvals("8thbitO_on_rx')); 
printf("8thbit1_on_rx = Zs\n"', s_getvals("8thbit1_on_rx'')); 
printf("'8thbitO_on_tx = %s\n", s_getvals(''8thbitO_on_tx")); 
printf ("'8thbit1_on_tx = %s\n"', s_getvals("8thbit1_on_tx')); 
} 
| f  ratieteetnieieieateinteananemaial END OF FILE: COMTEST.C cecrtrrtttrrrerrrrH= */ 
Listing 13-3. Assembly Language Portion of Package 
pooo------------------------------------------~------------------- 
; Filename: SERASM.ASM 
; Purpose: Assembly language routines to support interrupt 


ews ee *@e¢ Ve Be BSB WE 


handling in an asynchronous communication package 
for IBM PC and compatibles. 
Usage: Routines called from Microsoft C 4.0 programs. 


Copyright © 1986, 1987 Nabajyoti Barkakati 

Silver Spring, MD 20904 

Right to use, copy, and modify this code is granted for personal 
noncommercial use, provided that this copyright disclosure is 
retained on all copies. All other rights reserved. 
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; Date Started: 10-DEC-1986 

s Revisions: V1.00 9-FEB-1987--First working version. (NB) 
TITLE SERASM 

SERASM_TEXT SEGMENT BYTE PUBLIC ‘CODE' 

SERASM_TEXT ENDS 


e 


EXTRN _S_mainhndL|r:FAR 
ASSUME CS:SERASM_TEXT 
SERASM_TEXT SEGMENT 

PUBLIC _S_saveds 

PUBLIC _s_inthndltr 
PUBLIC _s_cli 

PUBLIC _s_sti 


’ 


save_ds: DW 860 ; Storage for DS 


_S_saveds PROC FAR 


PUSH ax 

MOV ax,ds 

MOV WORD PTR cs:save_ds,ax 
POP ax 


$_saveds ENDP 


me | 


_s_inthndlr PROC FAR 


PUSH bp 
PUSH ds 
PUSH es 
PUSH ax 
PUSH bx 
PUSH cx 
PUSH dx 
PUSH si 
PUSH di 
MOV ax, WORD PTR cs:save_ds ; Set DS to value 
MOV ds, ax ; saved earlier 
CALL _s_mainhndlr ; Call C int handler 
POP di 
continued 
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POP si 
POP dx 
POP cx 
POP bx 
POP ax 
POP es 
POP ds 
POP bp 
IRET 
_S_inthndlr ENDP 
; The following routine turns off interrupts. 
_s_cli PROC FAR 
CLI ; Turn off interrupts 
RET 3; and return. 
_s_cli ENDP 
; The following routine turns on interrupts. 
_S_sti PROC FAR 
STI ; Interrupts back on 
RET 3 and return. 
_s_sti ENOP 
SERASM_TEXT ENDS 
END 
a a END OF FILE: SERASM.ASM ------~-------------- 


Listing 13-4. The Circular Buffer (Queue) Package 


| Bon nn nw wn nn nn nn nn nn ee + + 5 ee «/ 
/* 

* Filename: QPAC.C 

* Implements a circular queue in Microsoft C 4.0. 

* 

* Copyright © 1986, 1987 Nabajyoti Barkakati 

* Copies may be made for noncommercial, private purposes only. 

* 

*/ 
| koe ee e+ + + x/ 


#Hinclude <stdio.h> 
#include <malloc.h> 


typedef struct QTYPE { 
continued 
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int count; 
int front; 
int rear; 
int elemsize; 
int maxsize; 
char *data; 

> QTYPE; 


QTYPE *q_setup(); 
char *q_getfrom(); 
int q_puton(), q_resetQ; 


/* qi_setup 
* Allocate a queue with room for specified number of characters. 
* The argument elemsize is the size of each data element. 
*/ 
QTYPE *q_setup(maxsize, elemsize) 
unsigned maxsize, elemsize; 
{ 
QTYPE *queue; 
if (Cqueue = (QTYPE *) calloc(1,sizeof(QTYPE))) == NULL){ 
fprintf(stderr,"Ran out of memory in queue setup! \n'); 
return(NULL); 
} 
queue->maxsize = maxsize; 
queue->elLemsize = elemsize; 


if ((queue->data = calloc(maxsize,elemsize)) == NULL){ 
fprintf(stderr,"No room for data in queue setup! \n'"); 
return(NULL); 

} 


/* Initialize queue */ 
queue->front = neg]1; 
queue->rear = -1; 
queue->count = 0; 
return (queue) ; 


/‘* qi_reset 
* Deallocate a queue and its data area. 
*/ 
int q_reset (queue) 
QTYPE *queue; 
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{ 
free (queue->data); 
free ((char *)queue); 
} 
| kon enn - - ee  --- - - e */ 


/‘* q_getfrom 
Copy next data element in queue to specified location. 
Also return the pointer to this element. 

*/ 

char *q_getfrom( queue, data ) 

QTYPE *queue; 

char *data; 


{ 
register int i, j; 
char *current; 
current = NULL; 
if(queue->front == -1) return(current); 
/* Else retrieve data. Copy elemsize characters into data. */ 
if (queue->elemsize == 1)¢ 


current = &(queue->datalqueue->front]); 
*data = *current; 

} 

else { 

for(i=0, j=queue->front * queue->elemsize; 

i<queue->elemsize; i++, j++) 

*(datati) = queue->dataljj; 

) 

current = 
&(queue->datalqueue->front * queue->elemsize]); 

} 

queue->count--; 

if (queue->count == 0) ¢ 

/* The queue is empty. Reset front and rear, and the count. */ 

queue->front = queue->rear = -1; 
return(current) 3 


} 
/* Increment front index and check for wraparound */ 

if (queue->front == queue->maxsize-1) { 
queue->front = 0; 

} 

else { 
queue->front++; 

} 


continued 
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return(current); 


/e* q_puton 
* Put a data element into queue. 
*/ 
int q_puton( queue, data) 
QTYPE *queue; 
char *data; 
{ 
register int i, j; 
/* First check if queue is full. Return 0 if full. 
if(queue->count == queue->maxsize) return(0); 
/* Else, adjust rear and check for wraparound */ 
if(queue->rear == queue->maxsize-1){ 
queue->rear = Q; 


} 

else { 
queue->reartt; 

} 


/* Save data in queue. Copy elemsize characters */ 

if (queue->elemsize == 1)¢ 
queue->data[queue->rear] = *data; 

} 

else { 
for(i=0, j=queue->rear * queue->elemsize; 

j<queue->elemsize; i++, j+t+)t 
queue->datalj] = *(datati); 


} 

queue->count++; 

if(queue->front == -1) queue->front = 0; 
return(1); /* Successfully inserted element */ 


[ko------------------- END OF FILE: QPAC.C ------- 


Listing 13-5. C Portion of Package, SERIAL.C 
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Filename: SERIAL.C 

Purpose: An asynchronous communication package for 
IBM PC and compatibles. Supports asynchronous 
communication adapters based on Intel 8250 
UART Cor compatible). 
This version was developed on an IBM PC-AT with 
an IBM Serial Card. DOS version 3.1 was used. 

Language: Microsoft C 4.0 

Usage: This a set of routines that provides basic 
functions for asynchronous communication. 
Call s_setvals to set parameters and s_getvals 
see parameter values. Call s_setup to setup 
port for communications. Use s_sendchar and 
S_rcvchar to send and receive characters 
respectively. A BREAK may be sent by calling 
s_sendbreak. 


Copyright © 1986, 1987 Nabajyoti Barkakati 

Silver Spring, MD 20904 
Right to use, copy, and modify this code is granted for personal 
noncommercial use, provided that this copyright disclosure is 
retained on all copies. All other rights reserved. 


Date Started: 1{0-DEC-1986 
Revisions: V1.00 9-FEB-1987--First working version. (NB) 


+ + £€ + ££ + + F + F FH FF £ FF F H FHF HF HF F FF HF HH HF 


#include <stdio.h> 
#include <ctype.h> 
#include <string.h> 
#include <dos.h> 

#incltude <conio.h> 


Hdefine TRUE 1 
#define FALSE O 
#define EOS ‘\0' 


/* Definitions for the 8259 Programmable Interrupt Controller */ 
#define P8259_0 0x20 /* Address of int control register */ 
Hdefine P8259_1 0x21 /* Address of int mask register */ 
H#define END_OF_INT 0x20 /* Nonspecific EOI */ 


/* Define some ASCII characters */ 
continued 
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H#define NUL_ASCII (0) 

#define XON_ASCII (0x11) 
Hdefine XOFF_ASCII (0x13) 
H#define DEL_ASCII (Ox7 fF) 


/* Address of BIOS data area (segment 40h, ofset 0) */ 
define BIOS_DATA (int *) (0x400000L)) 


/* Some interrupt vectors */ 
#define BIOS_RS232 0x14 
#define BIOS_TOD Oxia 


/* Defines for BREAK */ 
#define BREAK_ON 0x40 
#define BREAK_OFF Oxbf 


/*x Time of day interrupts occur once every 18.2 seconds */ 
H#define TOD_INTERVAL (1000.0/18.2) /* Interval in milliseconds */ 


/* The address of the comm port is in the integer 
* ‘comport’. This variable is initialized by reading from 
* the BIOS data area at segment 0x40. 


*/ 
H#define IER (comport + 1) /* Interrupt Enable Register */ 
#define IIR (comport + 2) /* Interrupt Identification */ 
#define LCR (comport + 3) /* Line Control Register */ 
#define MCR (comport + 4) /* Modem Control Register x/ 
#define LSR (comport + 5) /* Line Status Register */ 
#define MSR (comport + 6) /* Modem Status Register */ 


/* Individual Interrupt Enable Numbers */ 
H#define RDAINT 1 
H#define THREINT 2 
H#define RLSINT 4 
define MSINT 8 


/* Modem Control Register value */ 


define MCRALL 15 /x (OTR, RTS, OUT1 and OUT2 = 1) */ 
define MCROFF OQ /* Everything off */ 
/* Interrupt Enable Register value to turn on/off all int. */ 


Hdefine IERALL CRDAINT+THREINT+RLSINT+MSINT) 
H#define IEROFF O 
continued 
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/* Some masks for turning interrupts off */ 
fidefine THREOFF Oxfd 


/* Interrupt identification numbers */ 
H#define MDMSTATUS 0 
#define TXREGEMPTY 2 
#define RXDATAREADY 4 
#define RLINESTATUS 6 


/* Some flags */ 

Hdefine XON_RCVD 1 
H#define XOFF_RCVD O 
H#define XON_SENT 1 
H#define XOFF_SENT O 


/* Hi and low percentages for xon-xoff trigger */ 
H#define HI_TRIGGER(x) (3*x/4) 

H#define LO_TRIGGER(x) (x/4) 

/* Function to get bit 0 of an integer «/ 

#define bitO¢i) (i & 0x0001) 


/* Function to turn on interrupt whose "Interrupt Enable Number" 
* is 'i', in case it has been disabled. For example, the 

* THRE interrupt is disabled when an XOFF is received from the 

* remote system. 

*/ 

#define turnon_int(i, j) if CCCjSinpCIER))&i)==0) outpCIER, (j!i)) 


H#define report_error(s) fprintf(stderr,s) 


typedef struct QTYPE { 
int count; 
int front; 
int rear; 
int elemsize; 
int maxsize; 
char *data; 
} QTYPE; 


typedef struct VTBLTYPE { 
char *vname; 
int value; 
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} VTBLTYPE; 


typedef struct NTBLTYPE { 


char 


*pname; 


VTBLTYPE *vtblentry; 


int 


*p_value; 


VTBLTYPE *p_vtable; 


int 


vtblsize; 


+ NTBLTYPE; 


/* Functions accessible by user */ 

int s_sendchar(Q), s_rcvcharQ, s_setvals(), s_setupQ), 
s_cleanup(), s_txqemptyQ; 

void s_sendbreak(), s_delay(; 

char *s_getvals(); 


/* Global status indicators */ 
int s_linestatus, s_modemstatus, s_rbocount, s_totalcount, 
s_rlscount, s_rdacount, s_trmtycount, s_mscount; 


extern 
extern 
extern 
extern 


static 
static 
static 
static 
static 


static 


QTYPE *q_setup(); 

char *q_getfromQ); 

int q_puton(, q_reset(; 

void s_inthndlrQ, s_cliQ), s_stiO, s_saveds(); 


void s_rls(Q), s_rdaQ, s_trmty©, s_msQ; 
void (*p_newhndlr) (0); 

QTYPE *txq, *rxq; 

union REGS xr, yr; 

struct SREGS sr; 


VIBLTYPE b_tablel] = { 


"410", 0, 
"450", 1, 
"300", 
"600", 


"2400", 
"4800", 
"9600", 


3; 


static 
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2, 
3, 
"4200", 4, 
3. 
6, 
7 


VTBLTYPE p_tablel[] = { 
continued 


none", O, 
"odd", 1, 
"even", 3 
3; 
static VTBLTYPE s_table[] = { 
nqe 0, 
HOt. 1 
3; 
static VTBLTYPE w_tablel) = { 
GLY Le 2; 
nge 3 
3; 
static VTBLTYPE port_table[] = { 
ni ae 0, 
aOR 1 
3; 
static VTBLTYPE onoff_table[) = { 
"off, 0, 
"on", 1 
i; 
static int  port_number = 0, 
comport=0, 
baudrate = 4, 
parity = 0, 


stopbits = 0, 

wordlength = 3, 

txqsize = 1024, 

rxqsize = 2048, 
enable_xonxoff = 1, 
rcvd_xonxoff = XON_RCVD, 
sent_xonxoff = XON_SENT, 
null_ignore = TRUE, 
del_ignore = TRUE, 


bit7_1_rx = FALSE, 
bit?_O_rx = TRUE, 
bit7_1_tx = FALSE, 
bit7_O tx = FALSE, 
send_xon = FALSE, 

continued 
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send_xoff = FALSE, 

seg oldvector = 0, 
off_oldvector = 0, 
pckd_comparams = 0x83, 
int_number = 12; 
int_enable_mask = Oxef, 
int_disable_mask = 0x10; 


static NTBLTYPE pname_table[] = ¢ 


}: 


’ 


"baud", &(b_table[4]), &baudrate, 
b_table, (sizeof(b_table)/sizeof(VTBLTYPE)), 
"parity", &(p_table[0]),  &parity, 
p_table, (sizeof(p_table)/sizeof(VTBLTYPE)), 
"stopbits', &(s_table(01), &stopbits, 
s_table, (sizeof(s_table)/sizeof(VTBLTYPE)), 
"wordlength", &(w_table(1]), &wordlength, 
w_table, (sizeof(w_table)/sizeof(VTBLTYPE)), 
"port", &(port_table[0]), &port_number, 
-port_table, (sizeof(port_table)/sizeof (VTBLTYPE)), 
"xonxoff"', &Conoff_tablef1]), &enable_xonxoff, 


onoff_table, (sizeof (onoff_table)/sizeof (VTBLTYPE)) 
"null_ignore", &(onoff_tablel[1]), &null_ignore, 
onoff_table, (sizeof (onoff_table)/sizeof (VTBLTYPE)) 
"del_ignore", &Conoff_table[1]1), &del_ignore, 
onoff_table, (sizeof (onoff_table) /sizeof(VTBLTYPE) > 
"8thbitO_on_rx", &(onoff_tablel1]), &bit7_O_rx, 
onoff_table, (sizeof (onoff_table)/sizeof (VTBLTYPE)) 
"8thbit1_on_rx", &(onoff_table([0]), &bit?_1_rx, 
onoff_table, (sizeof (onoff_table)/sizeof(VTBLTYPE)) 
"8thbitO_on_tx", &(onoff_table[0]), &bit7_O_tx, 
onoff_table, (sizeof(onoff_table)/sizeof(VTBLTYPE) ) 
"8thbit1_on_tx", &Conoff_table(0]), &bit7_i_tx, 
onoff_table, (sizeof (onoff_table) /sizeof(VTBLTYPE) ) 


#define pnmtbl_size (sizeof (pname_table)/sizeof (NTBLTYPE)) 


* 
* 


*/ 


s_mainhndtlr 
Main interrupt handler for all serial port interrupts. 
Called by the assembly routine s_inthndlr. 


int s_mainhndtrQ 


{ 


continued 


e 


’ 


e 


e 
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int c; 
register int int_id, intmask; 
while (TRUE) ¢ 

/* Read the interrupt identification register, IIR */ 

int_id = inpC(IIR); 
if (bitOCint_id) == 1) { 

/* If bit 0 is 1, then no interrupts pending. Send an end of 
* interrupt signal to the 8259A Programmable Interrupt 
* Controller and then return. 

*/ 
outp(P8259_0, END_OF_INT); 
return; 

} 

s_totalcount++; 

if Cint_id >= RXDATAREADY) turnon_int (THREINT, intmask) ; 


/* Process interrupt according to id. 
* The following list is in increasing order of priority. 
*/ 
switch Cint_id) ¢ 
case MDMSTATUS: s_ms(); 


break; 
case TXREGEMPTY: s_trmtyQ; 
break; 
case RXDATAREADY: s_rda(); 
break; 
case RLINESTATUS: s_rls(); 
break; 
/* Just fall through if id is none of the above */ 
} 
} 
} 
[| Br nn en en ee ee ene x/ 


/* gs rls 

* Process a "receive Line status" interrupt 

*/ 

static void s_rls( 

{ 
register int intmask; 

/* Read Line status and save it in 's_linestatus’ */ 
s_linestatus = inp(LSR); 
s_rlscountt+; 


continued 
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/* s orda 
* Process a "receive data available" interrupt 
*/ 
static void s_rda() 
{ 

register int intmask; 

char c; 
/* Read from comport */ 

c = inp(comport); 

s_rdacountt+; 

ifCenable_xonxoff) { 

if(c == XON_ASCII) { 
revd_xonxoff = XON_RCVD; 

/* Turn on THRE interrupt if it's off. */ 
turnon_int (THREINT, intmask) ; 
return; 

} 
if(c == XOFF_ASCII) { 
revd_xonxoff = XOFF_RCVD; 

/* Turn off THRE interrupts. */ 
intmask = inpCIER); 
if Cintmask & THREINT) outpCIER, intmask & THREOFF); 
return; 


} 
if(null_ignore && c == NUL_ASCII) return; 
if(del_ignore && c == DEL_ASCII) return; 
if(bit7_1_rx) c |= 0x80; 
if(bit7_O rx) c & Ox7f; 
if€ q_puton(rxq, &c) == OC 
/* Increment receive buffer overflow count */ 
s_rbocount++; 
} 
/* Check if queue is almost (75%) full */ 
ifCenable_xonxoff)f{ 
if(rxq->count >= HI_TRIGGER(rxqsize) && 
sent_xonxoff != XOFF_SENT ) f 
/* Set flag to send XOFF */ 
send_xoff = TRUE; 
/* and turn on THRE interrupts so that we can send the XOFF */ 
turnon_int (THREINT, intmask) ; 
} 


continued 
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/‘* s_trmty 
* Process a "transmit holding register empty” interrupt 
*/ 
static void s_ trmtyQ 
{ 
char c; 
register int ierval; 


s_trmtycountt+; 


if (send_xoff == TRUE) { 
outp(comport, XOFF_ASCII); 
send_xoff = FALSE; 
sent_xonxoff = XOFF_SENT; 
return; 

} 

if Csend_xon == TRUE) { 
outp(comport, XON_ASCII); 
send_xon = FALSE; 
sent_xonxoff = XON_SENT; 
return; 


/* Put a character into the transmit holding register */ 
if(€ q_getfrom(txq, &c) != NULL){ 
if(bit7_1_tx) c |= 0x80; 
if(bit7_O tx) c & Ox7f; 
outp(comport, c); 
return; 
} 
/* Nothing to send--turn off THRE interrupts */ 
ierval = inpCIER); 
if Cierval & THREINT) outpCIER, ierval & THREOFF); 


/* Ss _oms 

* Process a "modem status" interrupt 
*/ 

Static void s_ms() 

{ 


continued 
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/* Read modem status and save in 's_modemstatus' */ 
s_modemstatus = inp(MSR); 
s_mscount++; 


/* gs setup 
Sets up everything for communication. Call this routine 
after parameter values have been specified (by s_setparams). 
Return 1 if setup successful, else return O. 


int s_setup(Q 


int i3 
static void s_intinitQ; 


if (port_number < 0 |} port_number > 1) 
report_error("Invalid port number! \n"); 
/x Get port address from BIOS data area and save in ‘comport’ */ 
comport = *(BIOS_ DATA + port_number); 
if (comport == O){ 
report_error(''BIOS could not find port! \n'); 
return(Q); 
} 
/* Set up masks for 8259A PIC. To enable interrupt from the 
* port this mask is ANDed with the mask register at 2th. 
* To disable, OR the disable mask with the mask register. 
* The interrupt number is 8+the IRQ level of the interrupt. 
* Com port 1 has IRQ 4, port 2 has IRQ 3. 
x/ 
if (port_number == 0) { 
int_enable_mask = Oxef; 
int_disable_mask = 0x10; 
int_number = 12; 
} 
if Cport_number == 1) { 
int_enable_mask = Oxf7; 
int_disable_ mask = 8; 
int_number = 11; 
} 
/* Get old interrupt vector and save it. Use DOS function 35h */ 
xr.h.ah = 0x35; 
xr.h.al = int_number; 
segread(&sr); 
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intdosx(&xr, &yr, &sr); 
off_oldvector = yr.x.bx; 
seg oldvector = sr.es; 


/x Install new interrupt service routine, use DOS function 25h */ 
p_newhndlr = s_inthndlr; 
xreh.ah = 0x25; 
xr.h.al = int_number; 
xr.x.dx = FP_OFF(p_newhndlr); 
segread(&sr); 
sr.ds = FP_SEG(p_newhndlr); 
intdosx(&xr, &yr, &sr); 


/* Set up communication parameters */ 
s_setcommparams(); 


/* Call assembly Language routine to save current value of DS */ 
s_saveds(); 


/* Setup the transmit and receive queues */ 

if ¢ (txq = q_setup(txqsize, sizeof(char))) == NULL ¢ 
report_error("Error creating transmit queue! \n''); 
return(0); 

} 

if ¢€ (rxq = q_setup(rxqsize, sizeof(char))) == NULL { 
report_error("Error creating receive queue! \n"); 
return(Q); 


/* Reset all counts and flags. */ 
s_rbocount = 0; 
s_totalcount = 0; 
s_rlscount = 0; 
s_rdacount = 0; 
s_trmtycount = 0; 
s_mscount = 0; 


rcvd_xonxoff = XON_RCVD; 
if (sent_xonxoff == XOFF_SENT) { 
send_xon = TRUE; 
} 
else { 
send_xon = FALSE; 
continued 
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} 
send_xoff = FALSE; 


/* Turn on interrupts from the comm port and setup 8259A */ 
s_cliQ); 
s_intinitQ; 
s_stiQ); 


return(1); 


/‘e* gs _ intinit 

* Start up interrupts from the serial board. Also set up 
8259A to accept the interrupts. This routine should be 

* invoked with the interrupts turned off, i.e., inside a 

* (CLI---STI) pair. 

*/ 

static void s_intinit( 

{ 


int intmask; 


/* Set up modem control register (port = MCR) */ 
outp(MCR, MCRALL); 


/* Enable all interrupts on the serial card (port = IER) */ 
outpCIER, IERALL); 


/* Read 8259A's interrupt mask register and write it back after 
* ANDing with int_enable_mask. 
*/ 

intmask = inp(P8259_1) & int_enable_mask; 

outp(P8259_1, intmask); 


/*¥ gs _cleanup 
* Cleanup after comm session is done. Turns off all interrupts. 
*/ 
int s_cleanup( 
{ 
Static void s_intoffQ; 


/* Turn off interrupts from serial card */ 
s_clid); 
continued 
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s_intoffQ; 
s_stiQ; 


Restore orginal interrupt vectors */ 
xr.h.ah = Ox25; 

xr.h.al = int_number; 

xr.x.dx = off_oldvector; 

sr.ds = seg_oldvector; 

intdosx(&xr, &yr, &sr); 


Deallocate space used by the transmit and receive queues */ 
q_reset (txq); 
q_reset (rxq); 


s_into ff 
Turn off all interrupts after comm session is done. 
Should be called with interrupts cleared. 

/ 

atic void s_intoff( 


int intmask; 


First reset the Interrupt Enable Register on the comm card * 
outpCIER, IEROFF); 


Turn off all bits of Modem Control Register */ 
outp(MCR, MCROFF); 


Next disable 8259A from recognizing ints at this IRQ level 
intmask = inp(P8259_1) | int_disable_mask; 
outp(P8259_1, intmask); 


s_setcommparams 
Set up basic communication parameters by using BIOS interrup 
number 14h, function 0 Cah=0). 

/ 

t s_setcommparams() 


/ 


*/ 


t 


/* Set up communication port parameters. Use BIOS INT 14h, AH=0 */ 


pckd_comparams = (baudrate << 5) | (parity << 3) | 
(stopbits << 2) | (wordlength); 
continued 
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xr.h.ah = O3 

xr.h.al = pckd_comparams; 
xr.x.dx = port_number; 
int86(BIOS_RS232, &xr, &yr); 


/* Copy status into "s_linestatus" and "s_modemstatus" */ 
s_linestatus = yr.h.ah; 
s_modemstatus = yr.h.al; 


/‘* s_vtblsrch 
* Searches a value string in specified table. Returns index if 
* found. Returns -1 if string not in table. (Internal Routine) 
*/ 
static int s_vtblsrch(string, table, size) 
char *string; 
VTBLTYPE «table; 
int size; 
{ 

int i; 

for (i = 0; i < size; i++) ¢ 

if ¢( (strempi(string, tablel[i].vname)) == 0) { 
return(id: 


} 
return(-1); 


/‘* s_setvals 
Set the value string for a named parameter. 
Return 1 if ok, O otherwise. 
*/ 
int s_setvals(name, vals) 
char *name, *vals; 
{ 
Static int s_vtblsrch(); 
int i, j, retval; 


retval = 0; 
/* First search table for parameter name */ 
for (i=0; i<pnmtbl_size; i++) { 
if (strcmpi(pname_tableli).pname, name) == 0) { 
/* Now search the table for the value string */ 
continued 
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if (Cj = s_vtblsrch(vals, pname_tableli].p_vtable, 
pname_tableli].vtblsize)) != -1) ¢ 
*(pname_tableli].p_value) = 
(pname_tablelil.p_vtable) [j].value; 
pname_tableLlil.vtblentry = 
&((pname_tablelil].p_vtable)[jJ); 
retval = 1; 


} 
break; 
} 
} 
return(retval); 
} 
| Bren rrr rn or nn a rrr ret rat xf] 


/* gs _getvatls 
Return the value string corresponding to a named parameter. 
Returns NULL in case of error. 

*/ 

char *s_getvals (name) 

char *name; 


{ 
int i; 
for (i=0; i<pnmtbl_size; i++) { 
if (strempi(pname_tableli].pname, name) == 0) ¢ 
return((pname_tableli].vtblentry)->vname); 
} 
} 
return(NULL); 
} 
| koe nn a rere */ 


/‘* s_sendchar 
* Puts a character into transmit queue. Returns 1 if all's ok, 
x OQ if there were problems. 
*/ 
int s_sendchar (ch) 
int ch; 
{ 
int retval, intmask; 


retval = q_puton(txq, &ch); 


/* Turn on THRE interrupt if it's off and an XOFF was not received*/ 


if (revd_xonxoff != XOFF_RCVD) turnon_int (THREINT, intmask) ; 
return(retval); 
continued 
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/‘k* s_revcechar 
* Returns a character from the receive queue. 
* Returns ~-1 if queue is empty. 
*/ 
int s_rcvchar() 
{ 
int ch, intmask; 
/* If we had sent an XOFF earlier, we might have to send an XON */ 
if Cenable_xonxoff){ 
if(rxq->count <= LO_TRIGGER(rxqsize) && 
sent_xonxoff != XON_SENT ) ¢ 
send_xon = TRUE; 
turnon_int (THREINT, intmask); 


} 
if (q_getfrom(rxq, &ch) == NULL) { 
return(-1); 


} 
else { 
return(ch); 
} 
} 
| keen nnn ne */ 


/‘* s_txqempty 
* Returns 1 if txq (transmit queue) is empty, else returns O. 
* Need when sending file. 


int s_txqempty() 


if (txq->count == 0) ¢{ 
return (TRUE); 


} 
else { 
return (FALSE); 
} 
} 
| koe on nn ee  - e  - - - - -- e */ 


/‘* s_ sendbreak 
* Send a break signal (hold Line in spacing state for 250 ms). 
*/ 
void s_sendbreak() 
continued 
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int lervals 

/* Turn on bit 6 of LCR to initiate BREAK signal */ 
Lerval = inp(LCR) | BREAK_ON; 
outp(LCR, lerval); 
s_delay(250.0); 

/* Turn off bit 6 of LCR to end the BREAK signal */ 
Lerval = inp(LCR) & BREAK_OFF; 
outp(LCR, lerval); 


/xex s_ delay 
* Delay for ‘d_ms'' milliseconds. Resolution ~55 milliseconds. 
* WARNING : This is a very “coarse” timer. 
*/ 
void s_delay(d_ms) 
double d_ms; 
{ 

int ticks; 

Long oldcount, newcount; 
/* Get timer ticks for this delay */ 

ticks = Cint)(d_ms / TOD_INTERVAL + 0.5); 

xr.h.ah = QO; 

int86(BIOS_TOD, &xr, &yr); 
/* On return CX has high count and DX has low count. 
* The high count is incremented every 65,536 low counts. 
*/ 

oldcount = (long)(€ (long) Cyr.x.cx) << 16) | 

(unsigned) yr.x.dx); 

newcount = oldcount; 
/* Now keep checking count until difference between new and 
* old counts is ‘ticks’. 
*/ 

while ((newcount - oldcount) < ticks) { 

int86(BIOS_TOD, &xr, &yr); 
if (yr.h.al != 0) { 
/* The timer has crossed 24 hours */ 
newcount = (long) ((€ 24L << 16) | Cunsigned) yr.x.dx); 


} 
else { 
newcount = (long) (¢€ (long) Cyr.x.cx) << 16) | 
(unsigned) yr.x.dx); 
} 


continued 


531 


Section 3: Working with the Hardware Interface 


[k------~------------ END OF FILE: SERIAL.C ------------------- */ 


The source code for the serial communications package described in this 
article is available on a 360KB double-sided double-density IBM PC diskette 


(DOS 3.1) for $9.95. (check or a money order) from LNB Software, Inc.; 
2005 Aventurine Way; Silver Spring, MD 20904. 
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Note that although we have presented all pertinent details necessary to develop a 
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ing read this essay, you will not find it necessary to do so—at least not until you 
need information on exact meanings of the internal registers of the asynchro- 
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. 1984. Options and Adapters Technical Reference Manual. Part #6322509. 
North Tarrytown, New York. 
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Understanding Expanded 
Memory Systems 


Ray Duncan 


The Intel 8086 and 8088 microprocessors, which serve as the heart of the orig- 
inal IBM PC and most of its compatibles, can directly address up to one megabyte 
of memory. In the IBM PC architecture, the bottom 640K of this address space is 
available for use by MS-DOS and the programs which run under its control. The 
upper 384K are reserved for use by various adapter boards and for test pro- 
grams and device drivers in read-only memory (ROM). Personal computers 
based on the Intel 80286 and 80386 microprocessors are physically capable of 
addressing much larger amounts of RAM, but run MS-DOS in so-called real 
mode (8086 emulation mode) where they are still subject to the same one-mega- 
byte limitation. 

In the early days of the IBM PC and MS-DOS, a 640K program space seemed 
simply enormous. After all, most of the first MS-DOS programs were ported 
from 8080 and Z-80 systems running under CP/M, where 64K of memory was 
the maximum and 32K systems were not unusual. But within three years, sev- 
eral events conspired to make the 640K space seem suddenly crowded after all. 
Completely new applications were written that were able to take full advantage 
of the larger address space, a new class of immensely popular applications 
called Terminate and Stay Resident (TSR) emerged, and MS-DOS itself rapidly 
grew larger as it was enhanced to support networks and fixed disks. (See Essay 1, 
A Guided Tour inside MS-DOS, by Harry Henderson, for a general discussion of 
changes in MS-DOS, and Essay 7, Safe Memory-Resident Programming (TSR) by 
Steven Baker.) 


Lotus, Intel, Microsoft EMS 


In order to prolong the useful life of the 8086/88-based PCs, Lotus Development 
Corporation and Intel Corporation worked together on a method to increase the 
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amount of fast storage available to MS-DOS applications. The result of their col- 
laboration, the Expanded Memory Specification (EMS) version 3.0, was an- 
nounced at the Spring COMDEX in 1985. Shortly afterward, Microsoft 
announced support for the EMS, and that Microsoft Windows would be up- 
graded to use the memory made available by EMS hardware and software. EMS 
version 3.2, modified from 3.0 to add support for multitasking operating sys- 
tems, was released in August 1985 as a joint effort of Lotus, Intel, and Microsoft 
and is commonly referred to as the LIM EMS. 


Enhanced Expanded Memory 


In response to the first Intel and Lotus announcement, AST Research, a manu- 
facturer of popular add-on memory boards for IBM PC compatibles, formulated 
a competitive memory expansion approach called the Enhanced Expanded 
Memory Specification (EEMS). The AST design was upward compatible from the 
original EMS, but technically more complex and specifically directed at improv- 
ing the performance of multitasking operating systems. It was subsequently en- 
dorsed by Ashton-Tate and Quadram, modified for compatibility with the LIM 
EMS version 3.2, and became popularly known as the AQA EEMS. 

In August 1987, Lotus, Intel, Microsoft, and the other interested parties an- 
nounced Expanded Memory Specification version 4.0. EMS 4.0 reconciles the 
previous EMS 3.2 and EEMS specifications, is upward compatible from EMS 3.2, 
raises the limit on the maximum amount of expanded memory which may be 
installed in a system, and adds many new capabilities for the benefit of mul- 
titasking program managers such as DESQView and Microsoft Windows. 

It is apparent, as this book goes to press, that the Expanded Memory Speci- 
fication has been a tremendous success. EMS compatible expansion boards are 
available from scores of manufacturers, and an incredible variety of software 
products, including all of the most popular spreadsheets and integrated envi- 
ronments, have been revised to take advantage of EMS memory when it is availa- 
ble. (Representative products that support Lotus/Intel/Microsoft EMS and/or 
AST Research/Quadram/Ashton-Tate EEMS are included in the Reading List at 
the end of this essay.) 


What Is Expanded Memory? 
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The Lotus/Intel/Microsoft EMS and the AST/Quadram/Ashton-Tate EEMS are 
functional specifications of bank-switched memory subsystems. Bank-switch- 
ing is a technique whereby one out of many logical memory pages can be made 
available for access by the central processor in a window at a predetermined 
physical address, somewhat like bringing one card out of a deck to the top 
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where it can be read. It was first widely employed on Apple II and S-100 bus 
computers in the late 1970s, to overcome the memory size limitations and the 
slow floppy disk access times on those machines. 

An EMS or EEMS compatible memory subsystem consists of one or more 
user-installable expanded memory boards which are plugged into the IBM PC 
expansion bus and resident driver program—the Expanded Memory Manager 
(EMM)—provided by the board manufacturer. Together, the boards and driver 
allow an application program to gain access to as much as 8 megabytes of ran- 
dom access storage (32 megabytes in the case of EMS 4.0) in a hardware-inde- 
pendent manner. The application calls on the driver to map 16K pages of 
expanded memory in and out of the microprocessor’s usual 1-megabyte address 
space as they are needed (see Figure 14-1). The driver accomplishes this mapping 
by writing expanded memory logical page numbers to specific CPU I/O ports, 
which are in turn physically connected to page registers on the memory boards. 


Expanded Memory 
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Fig. 14-1. Relationship of expanded memory to conventional 
memory. 
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The EMS 3.2, EEMS, and EMS 4.0 specifications differ mainly in where the 
expanded memory pages may be mapped to main memory, and how many pages 
may be so mapped simultaneously. LIM EMS 3.2 allows four 16K pages to be 
mapped at a time into a contiguous 64K area called a page frame. The location of 
the page frame is user-configurable so that it will not conflict with other hard- 
ware expansion options, but it is always located above the 640K area controlled 
by MS-DOS. Thus, since the expanded memory pages lie outside the area recog- 
nized by the operating system, they cannot be used for the execution of pro- 
grams but only for storage of data. 

In the AQA EEMS or EMS 4.0 design, on the other hand, more than four 
expanded memory pages can be mapped into memory at once, and the pages 
can be mapped anywhere within the CPU's one-megabyte address space. This 
makes it possible for specially designed multitasking managers (such as Quarter- 
deck System's DESQView) or operating systems (such as Digital Research’s Con- 
current PC-DOS) to use expanded memory for storage of executable program 
code and very fast switching between processes. However, for upward compati- 
bility with the LIM EMS 3.2, the AQA EEMS and EMS 4.0 require that the mem- 
ory area used to map the first four 16K pages (referred to in the the AQA EEMS 
as windows) be contiguous. 


Expanded Memory vs. Extended Memory 


Expanded memory should not be confused with extended memory. Although 
the two terms sound almost identical, they refer to completely different types of 
storage. Extended memory is the term used by IBM to refer to the memory at 
physical addresses higher than 1 megabyte (100000H) that may be accessed by 
an 80286 or 80386 microprocessor executing in protected mode. Since MS-DOS 
runs on these processors in real mode, extended memory is not directly accessi- 
ble to MS-DOS-based application programs. Most machines contain ROM BIOS 
routines and special hardware support that allow it to be used for storage by 
electronic disk (RAMdisk) drivers, however. 

Protected mode operating systems such as Microsoft's XENIX or OS/2, on 
the other hand, can take full advantage of extended memory for storage of both 
executable programs and data. Protected-mode 80386 virtual machine manag- 
ers, such as Windows/386, can even take advantage of the 80386's page registers 
to simulate the presence of expanded memory by remapping extended memory. 


Expanded Memory Manager 


The EMM provides the hardware-independent interface between application 
programs and the expanded memory board(s). The EMM is supplied by the man- 
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ufacturer in the form of an installable device driver compatible with MS-DOS 
version 2.0 or later. (See Essay 10, Developing MS-DOS Device Drivers, by Walter 
Dixon, for the theory and practice of installable device drivers.) The EMM itself 
is not sensitive to the version of MS-DOS that is running, but installable device 
drivers were not supported under MS-DOS versions 1.0 and 1.1. 

The user installs the EMM by copying the file containing the driver to his 
boot disk, adding a DEVICE= directive to the CONFIG.SYS file, and restarting the 
system. Internally, the EMM is divided into two distinct components: the driver 
and the manager. 

The driver portion contains some of the elements of a genuine installable 
character device driver, in that it includes Initialization and Output Status sub- 
functions and a valid device header. These elements allow the EMM to be incor- 
porated into the environment in an orderly way, and provide a means for 
application software to test for the driver's presence using conventional operat- 
ing system services. 

The manager element of the EMM is the true interface between application 
software and the expanded memory hardware. The LIM EMS defines the serv- 
ices to be provided by the EMM, including 


= status of the expanded memory subsystem 

m= allocation of expanded memory pages 

- mapping of logical pages into physical memory 
‘ deallocation of expanded memory pages 
“support for multitasking operating systems 


ix diagnostic routines 


The EMS also specifies how the EMM services are invoked, what parame- 
ters they accept, and what results they will return. 

The AQA EEMS redefines the software interface between application soft- 
ware and the EMM from that used in LIM EMS 3.2 only slightly, extending the 
definition of one of the EMS 3.2 functions and adding one new function in order 
to remove the restrictions on the mapping regions and the number of pages 
which may be mapped simultaneously. 

The LIM EMS 4.0, in its turn, defines about 40 new functions and subfunc- 
tions. Since the EMS 4.0 functions are mainly used by program managers and 
operating systems, they will not be described in detail in this essay. 

Application programs communicate with the EMM directly via a software 
interrupt INT 67H. The MS-DOS operating system kernel does not take part in ex- 
panded memory manipulations and does not make any use of expanded memory 
for its own purposes. However, some multitasking manager programs that run on 
top of MS-DOS, such as Microsoft Windows and Quarterdeck System's DESQview, 
are able to use expanded memory for swapping program code and/or data. 
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Testing for Expanded Memory 
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Before it attempts to use expanded memory for storage, an application program 
must establish that the Expanded Memory Manager is present and functional, 
and then it must call the driver to check the status of the memory boards them- 
selves. There are two methods a program can use to test for the existence of the 
EMM. 

The first technique is to issue an open file or device request INT 21H (Func- 
tion 3DH), using the guaranteed device name of the EMM driver, EMMXXXX0O. If 
the open operation succeeds, either the driver is present or there is a file with 
the same name in the current directory of the default disk drive. The application 
can then issue IOCTL Get Device Information INT 21H (Function 44H Subfunction 
OOH) and IOCTL Get Output Status INT 21H (Function 44H Subfunction 07H) re- 
quests to further qualify the existence and status of the driver. In any case, the 
handle that was obtained from the open function should be closed INT 21H (Func- 
tion 3EH) so it can be reused for another file or device. The open method is dem- 
onstrated in the following listing: 


s attempt to "open'’ EMM 
; 


mov dx,seg emm_name DS:DX = addr. of name 


mov ds,dx ; of Expanded Memory Manager 
mov dx,offset emm_name 
mov ax,3d00h : Function 30H, Mode=00H 
s = open, read-only 
int 2th s transfer to MS-DOS 
je error 3; jump if open failed 


: open succeeded, make sure 
> it was not a file 


s 
mov bx,ax : BX = handle from open 
mov ax,4400h 3 Function 44H Subfunction OOH 

s = IOCTL Get Device Information 
int 2th : transfer to MS-DOS 
je error : jump if IOCTL call failed 
and dx,80h : Bit 7 = 1 if character device 
jz error ; jump if it was a file 


; EMM is present, make sure 
: it is available... 
; (BX still contains handle) 


mov 


int 
je 
or 
jz 


mov 
int 
jc 


emm_name 


ax,4407h 


2th 
error 
al,al 
error 


ah,3eh 
2th 
error 


db 'EMMXXXX0' ,0 


e 
’ 
. 
& 
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Function 44H subfunction O7H 
= IOCTL Get Ouput Status 
transfer to MS-DOS 

jump if IOCTL call failed 
test device status 

if AL=0 EMM is not available 


now close handle 

(BX still contains handle) 
Function 3EH = Close 
transfer to MS-DOS 

jump if close failed 


guaranteed device name for 
Expanded Memory Manager 


The second method of testing for the driver is to use the address that is 
found in the vector for INT 67H to inspect the device header of the presumed 
EMM. The contents of the vector can be obtained conveniently with INT 21H 
(Function 35H). If the EMM is present, the name field at offset OAH of the device 
header contains the eight-byte ASCII string, EMMXXXXO. This method is highly 
reliable and it avoids the overhead of an open operation, but it is considered less 
“well-behaved” because it involves inspection of memory that does not belong to 
the application. The get interrupt vector technique is illustrated in the following 


listing: 


emm_int 


mov 


equ 67H 


al,emm_int 
ah,35h 
21h 


di,10 


=e 


=e 


me we 


=e =e =e =e 


me me =e =e 


Extended Memory Manager 
software interrupt 


first fetch contents of 
EMM interrupt vector... 
AL = EMM int. number 

fxn 35H = get vector 
transfer to MS-DOS 

now ES:BX = handler addr. 


assume ES:00000 points 
to base of the EMM... 
ES:DI = addr. of name 
field in Device Header 
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mov si,offset emm_name 


mov cx,8 s length of name field 
cld 

repz cmpsb 3; compare names... 

jnz error ; jmp if driver absent 


emm_name db ‘'EMMXXXX0' guaranteed device name for 


Expanded Memory Manager 


=e =e 


Using Expanded Memory 
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It is not uncommon for several programs, such as electronic disks (RAMdisks), 
TSR utilities, and foreground application programs, to be using expanded mem- 
ory for storage at the same time. Accordingly, it is important that each program 
treat expanded memory as a system resource like a file or peripheral device, 
and employ only the documented EMM services to allocate, access, and release 
expanded memory pages. Otherwise, the data belonging to one or more of the 
programs may be corrupted or destroyed. 

Once it has established that the Expanded Memory Manager is present, the 
application program bypasses MS-DOS and communicates with the EMM di- 
rectly via software INT 67H. The general calling sequence is 


mov ah,function s AH selects EMM function 


: : load other registers with 
; values specific to the 
s requested service 


int 67h s transfer to EMM 


In general, registers ES:DI are used to pass the address of a buffer or an 
array, and register DX holds an expanded memory handle, a 16-bit token re- 
turned by the EMM when a program first allocates some expanded memory 
pages and used by the program for subsequent access to those pages. Some 
EMM functions also use the AL and BX to pass such information as logical and 
physical page numbers. 

Upon return from an EMM function call, register AH contains zero if the 
function was successful. Otherwise, AH contains an error code with the most 
significant bit set, from the selection listed in Table 14-1. 


Table 14-1. 
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Expanded Memory Manager Error Codes 


a SS 


Error Code 


Significance 


_—_—— —_-_--—————————————— eee 


00H 
80H 


81H 
82H 


83H 
84H 
85H 
86H 
87H 


88H 


89H 
8AH 


8BH 
8CH 
8DH 
8EH 


8FH 


Function was successful 

Internal error in the expanded memory manager software (Possible 
causes include a logical error in the driver itself or damage to the mem- 
ory image of the driver.) 

Malfunction in the expanded memory hardware 

Memory manager is busy {It is already processing an expanded memory 
request.) 

Invalid expanded memory handle 

Function requested by the application is not defined 

No more expanded memory handles available 

Error in save or restore of mapping context 

An allocation request specified more logical pages than are physically 
available in the system (No pages were allocated.) 

An allocation request specified more logical pages than are currently 
available in the system (The request does not exceed the physical pages 
that exist, but some are already allocated to other EMM handles; no 
pages were allocated.) 

Zero pages cannot be allocated 

The logical page that was requested for mapping is outside the range of 
logical pages assigned to the handle 

Illegal physical page number in mapping request (not in the range 0-3) 
The save area for mapping contexts is full 

Save of mapping context failed, because save area already contains a con- 
text associated with the requested handle 

Restore of mapping context failed, because save area does not contain a 
context for the requested handle 

Subfunction parameter not defined 


Other values are typically returned in registers AL and BX or in a user- 
specified buffer. The parameters and returned results for the various functions 
supported by the EMS and EEMS compatible EMMs are summarized in Tables 
14-2 and 14-3. EMS Functions 49H and 4AH (not listed) were defined in EMS ver- 
sion 3.0 and are “reserved” in later EMS versions. 


Table 14-2. Expanded Memory Manager Interface 

SE UIE Ee 

Function 

Name Action Call With Returns Comments 

Get Manager ‘Test whetherthe AH = 40H AH = status This call is used after the 

Status expanded memory program has established that 
software and hard- the Expanded Memory Man- 
ware are func- ager is present in the system. 
tional. 

Get Page Frame Obtain the segment AH = 41H AH = status BX The page frame is divided 

Segment address of the = segment of into four 16K pages, which 
EMM page frame. page frame, if are used to map logical ex- 

AH = 0 panded memory pages into 
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Table 14-2. (cont.) 
Function 
Name Action Call With Returns Comments 
the physical memory space 
of the 8086/8088 processor. 
Get Expanded Obtainthe number AH = 42H AH = status BX The application need not 
Memory Pages of logical expanded = unallocated _ have already acquired an 
memory pages pages, if AH = EMM handle to use this func- 
present in the sys- 0 DX = total tion. 
tem and the num- EMS pages in 
ber of pages that system 
are not already al- 
located. 
Allocate Ex- Obtains an EMM AH = 43H BX = AH = statusDX Equivalent of a file open 
panded Mem- handle and allo- logical pages to = EMM handle, function for the EMM. The 
ory cates logical ex- allocate if AH = 0 handle that is returned is 
panded memory analogous to a file handle, 
pages to be con- and owns a certain number 
trolled by that han- of EMM pages. The handle 
dle. must be used with every sub- 
sequent request to map 
memory, and must be re- 
leased by a close operation. 
Map Memory Map oneofthelog- AH = 44H AL AH = status The logical page number 
ical pages of ex- = physical page must be in the range (0... 
panded memory (0-3) BX = logi- n— 1), where n is the num- 
assigned toahan- cal page (0... ber of logical pages pre- 
dle onto one of the n-1)DX = viously allocated to the EMM 
four physical pages EMM handle handle with Function 43H. 
within the EMM's To actually access the mem- 
page frame. ory once it has been mapped 
to a physical page, the appli- 
cation also needs the seg- 
ment of the EMM’s page 
frame, obtained with Func- 
tion 41H. 
Release Handle Deallocate the logi- AH = 45HDX AH = status This function is the equiva- 
and Memory cal pages of ex- = EMM handle lent of a close operation on a 
panded memory file. It notifies the EMM that 
currently assigned the application will not be 
to a handle, and making further use of the 
then release the data it may have stored 
handle itself for re- within expanded memory 
use. , pages. 
Get EMM Return the version AH = 46H AH = status AL The returned value is the 
Version number of the Ex- = EMM ver- version of the EMS with 
panded Memory sion, if AH = 0 which the driver complies. 
Manager software. The version number is en- 
coded as BCD, with the inte- 
ger part in the upper four 
bits, and the fractional part 
in the lower four bits. 
Save Mapping Savethecontents AH = 74H DX = AH = status This function is designed for 
Context of the expanded EMM handle use by interrupt handlers 
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and resident drivers or utili- 
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Function 
Name 


Action 


Call With 


Returns 


Comments 


Oe -- rOr———————  eeeeeee 


Restore Map- 
ping Context 


Get Number of 
EMM Handles 


Get Pages 
Owned by 
Handle 


Get Pages for 
All Handles 


Get/Set Page 
Map 


ping registers on 
the expanded 
memory boards, 
associating those 
contents with a 
specific EMM han- 
dle. 


Restore the con- 
tents of all ex- 
panded memory 
hardware page- 
mapping registers 
to the values associ- 
ated with the given 
handle. 


Return the number 
of active EMM han- 
dles. 


Return the number 
of logical expanded 
memory pages allo- 
cated to a specific 
handle. 


Return an array 
that contains all the 
active handles and 
the number of logi- 
cal expanded mem- 
ory pages 
associated with 
each handle. 


Save or set the con- 
tents of the page- 
mapping registers 
on the expanded 
memory boards. 


AH = 48H DX 

= EMM handle 
AH = 4BH 

AH = 4CH Dx 

= EMM handle 
AH = 4DH DI 


= offset of ar- 
ray to receive in- 
formation ES = 
array segment 


AH = 4EH AL 
= subfunction 
number DS:SI = 
array holding 
mapping infor- 
mation (subfunc- 
tions 1, 2) ES:DI 


AH = status 


AH = status BX 
= number of 
EMM handles, if 
AH = 0 


AH = status BX 
= logical pages, 
if AH = 0 


AH = status BX 
= number of 
active EMM han- 
dies IF AH = 0, 
array is filled in 
as described in 
comments col- 
umn 


AH = status AL 
= bytes in page- 
mapping array 
(subf. 3) Array 
pointed to by 
ES:DI receives 
mapping infor- 


ties that must access ex- 
panded memory. The handle 
supplied to the function is 
the handle that was assigned 
to the interrupt handler dur- 
ing its initialization sequence, 
not to the program that was 
interrupted. 

Use of this function must be 
balanced with a previous call 
to EMM function 47H. It al- 
lows an interrupt handler or 
resident driver which used 
expanded memory to restore 
the mapping context to its 
state at the point of interrup- 
tion. 

If the number of handles re- 
turned is zero, none of the 
expanded memory is in use. 
The number of active EMM 
handles never exceeds 255. A 
single program can make 
several allocation requests 
and therefore own several 
EMM handles. 

The number of pages re- 
turned is always in the range 
1-512 if the function is suc- 
cessful. An EMM handle 
never has zero pages of 
memory allocated to it. 

The array is filled in with 
two-word entries. The first 
word of each entry contains 
a handle, and the second 
word contains the number of 
pages associated with that 
handle. The value returned 
in BX gives the number of 
valid two-word entries in the 
array. Because 255 is the 
maximum number of EMM 
handles, the array need not 
be larger than 1020 bytes. 
Subfunctions: 0 = get map- 
ping registers into array 1 = 
set mapping registers from 
array 2 = get and set map- 
ping registers in one opera- 
tion 3 = return needed size 
of page-mapping array (This 
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Call With Returns 

= array to re- mation, for sub- 
ceive informa- functions 0 and 
tion 2 

(subfunctions) 


Comments 


function was added in EMS 
version 3.2 and is designed to 
support multitasking. It 
should not ordinarily be used 
by application programs.) 
The content of the array is 
hardware. 


ve 


Modified or Additional Expanded Memory Manager 


Functions Defined by the AST/Quadram/ Ashton-Tate 


(a 


Table 14-2. (cont.) 
Function 
Name Action 
EEMS 
Function 
Name Action 


Map Memory Map one of the log- 


ical pages of ex- 
panded memory 


assigned to a han- 
dle onto one of the 


EMM%ss physical 
windows. 


Get Physical 


Window Ar- of mapping win- 


ray dows and an array 
containing the ad- 


dresses of those 
windows. 


Obtain the number 


Call With 


AH = 44H AL = 
window no. (see 
comment) BX = 
logical page (0 
...n-1)DX = 
handle 


Returns 


AH = status 


AH = 60HES:DI AH = status AL = 

= address of ar- number of win- 

ray dows Array re- 
ceives window- 
mapping informa- 
tion 


Comments 


The logical page number 
must be in the range (0... 
n — 1), where n is the num- 
ber of logical pages pre- 
viously allocated to the EMM 
handle with Function 43H. 
The window number must 
be within the range re- 
turned by the EEMS function 
60H (see below). The first 
four windows are mapped 
contiguously for EMS com- 
patibility. 

This function fills in the ar- 
ray with a list of the physical 
page windows available. 
Each entry in the array is 
one byte in length and cor- 
responds to a physical page 
number that contains the 
most significant six bits of 
the segment address. 


a tt 


Strategy for Using Expanded Memory 


Although the EMM software interface may appear somewhat forbidding at first 
glance, it is really very easy to use. The general strategy for use of expanded 
memory by an application program is quite straightforward: 
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. Establish the presence of the EMM by one of the two methods demon- 
strated in the earlier examples. If the EMM cannot be found, the applica- 
tion must either terminate or proceed using conventional memory 
resources only. 


. Once the driver is known to be present, check its operational status with 
EMS Function 40H. This function verifies that the EMM has been prop- 
erly initialized during the system boot process, and that the EMS hard- 
ware is functioning correctly. 


. Check the version number of the EMM with EMS Function 46H to ensure 
that all services the application will request are available. For example, if 
the application makes use of EMS Function 4EH, it must ensure that it is 
running with version 3.2 or greater of the EMM rather than 3.0. The al- 
gorithm to be used by the program is as follows: 


a. Issue INT 67H with AH = 46H. If AL = 40H, the EMM is compatible 
with EMS version 4.0. If AL = 30H, the EMM is compatible with 
EMS version 3.0. If AL = 32H, proceed to step 3b. 


b. Issue INT 67H with AH = 60H. If an error is returned (AH not zero), 
the EMM is compatible with LIM EMS version 3.2. If AH is zero 
upon the return, the EMM is compatible with the AQA EEMS. 


. Obtain the segment of the EMS compatible page frame used by the EMM 
with EMS Function 41H. Applications exploiting the additional mapping 
capabilities of the EEMS must obtain the additional window addresses 
with EEMS Function 60H. 


. Allocate the desired number of expanded memory pages with EMS Func- 
tion 43H. If the allocation is successful, the EMM returns a handle that is 
used by the application to refer to the expanded memory pages that it 
owns. This step is exactly analogous to opening a file and using the han- 
dle obtained from the open function for read/write operations on the 
file. 


. If the requested number of pages are not available, the application can 
query the EMM for the actual number of pages available (EMS Function 
42H) and determine whether it can continue in a degraded fashion. 


. Once the application has successfully allocated the number of expanded 
memory pages it needs, it uses EMS Function 44H to map logical pages in 
and out of the physical page frame, in order to store and retrieve data in 
expanded memory. 


. When the program finishes using its expanded memory pages, it must 
release them by calling EMS Function 45H before it terminates and re- 
turns control to MS-DOS. Otherwise, the pages will be lost to use by 
other programs until the system is restarted. 
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The following is a program skeleton that illustrates this general approach 
to the use of expanded memory. This code assumes that the presence of the 
EMM has already been verified with one of the techniques shown earlier. 


mov ah,40h s test EMM status 
int 67h 
or ah,ah 


jnz error jump if bad status from EMM 


me 


mov ah,46h : check EMM version 
int 67h 
or ah,ah 


jnz error 


jump if couldn't get version 


cmp al,030h make sure it is at least ver. 3.0 


job error jump if wrong EMM version 
mov ah,41th s get page from segment 
int 67h 


or ah,ah 
jnz error 
mov page_frame,bx 


jump if failed to get frame 
save segment of page frame 


=e “5 


mov ah,42h : get no. of available pages 
int 67h 

or ah,ah 

jnz error jump if get pages error 


mov total_pages,dx 
mov avail_pages,bx 


save total EMM pages 
save available EMM pages 


=e %e 6 


or  bx,bx 

j2 error s abort if no pages available 
mov ah,43h ; try and allocate EMM pages 
mov bx,needed_pages 

int 67h : if allocation is successful 
or ah,ah 


jnz error jump if allocation failed 


mov emm_handle,dx j; save handle for allocated page 


now we are ready for other 
processing using the EMM pages 


e 
ee me 
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; map in EMS memory page... 
mov bx, log_page ; BX <- EMS Logical page number 
mov al,phys_page ; AL <- EMS physical page (0-3) 
mov dx,emm_handle ; EMM handle for our pages 


mov ah,44h ; Function 44H = map EMS page 
int 67h 

or ah,ah 

jnz error ; jump if mapping error 


program ready to terminate, 
give up allocated EMM pages... 


mov dx,emm_handle handle for our pages 


me 6% 68 US 


mov ah,45h EMS Function 6 = release pages 
int 67h 

or ah,ah 

jnz error ; jump if release failed 


To ensure that it will not be terminated unexpectedly by events that are not 
under its control, any program that uses expanded memory should replace the 
system's default handlers for Control-C and Critical Error exceptions with its 
own handlers, the addresses of which are stored in the vectors for INT 23H and 
INT 24H, respectively. These new handlers would be responsible for releasing ex- 
panded memory pages owned by the application and cleaning up any other 
loose ends before returning control to MS-DOS and allowing the application to 
be terminated. 


Device Drivers, TSRs, and Expanded Memory 


A TSR, interrupt handler, or installable device driver (such as an electronic disk) 
that uses expanded memory follows the same general procedure outlined above, 
but with a few minor variations. These variations are imposed by the fact that 
the program may be executing as a result of a hardware interrupt or during the 
system boot process. 

If the program is a device driver, it will need to test for the existence of the 
EMM and allocate expanded memory pages during its Initialization routine, 
which is called when the driver is loaded into memory and before the operating 
system is fully functional. Consequently, the driver must use a modified version 
of the get interrupt vector method of testing for the existence of the EMM, fetch- 
ing the contents of the INT 67H vector directly rather than using INT 21H (Function 
35H). Of course, the user must be warned to place the DEVICE=line that loads the 
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EMM before the DEVICE= line that loads the driver that uses expanded memory 
services. 

TSRs and interrupt handlers are usually initialized in a more normal sys- 
tem context (i.e., they are typically first loaded as though they were normal pro- 
grams from COM or EXE files). Therefore, they can test for the EMM'’s presence 
like any other application program. 

When a TSR, device driver, or interrupt handler acquires control and 
needs to access its expanded memory pages, it must first save the EMM context 
with a call to EMM Function 47H. This function stores the current contents of 
the page-mapping registers on the EMS hardware and any other hardware-de- 
pendent information, which will be needed later to restore the exact same state 
of the EMS subsystem, into an internal buffer. Note that the EMS context which 
is being saved belongs to the foreground application program that was inter- 
rupted, but the context is saved in association with the EMM handle owned by 
the background program, handler, or driver which has asserted control. 

When the background program is finished using expanded memory, it calls 
EMM Function 48H, which restores the expanded memory hardware to its state 
at the point of interruption, so that the expanded memory page-mappings pre- 
viously requested by the foreground program are again valid. This is an abso- 
lutely vital step since the foreground program assumes that its expanded 
memory pages are always available within the page frame after it has requested 
them to be mapped. It has no way to know that it has been temporarily sus- 
pended by a background program that also used the same page frame for ex- 
panded memory access. 

A driver, interrupt handler, or TSR typically owns its expanded memory 
pages on a permanent basis (until the system is restarted) and never deallocates 
them. For example, an electronic disk which is using expanded memory to emu- 
late a physical disk device would have no reason to ever change its initial page 
allocation, since block devices do not change size dynamically while the system 
is running! 
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As a practical example of the use of expanded memory pages, Listing 14-1 con- 
tains an assembly language subroutine package EMSPROCS.ASM that allows C pro- 
grams to test for the existence of the EMM, test its status, and allocate, map, and 
deallocate expanded memory pages. The package is compatible with EMS 3.2, 
EEMS, or EMS 4.0. The functions supported are listed in Table 14-4. 

When an error occurs on an EMM function call, the actual error code re- 
turned by the expanded memory manager is stored in the variable _emserr, 
which can be declared external in the C program and then accessed as the static 
integer variable emserr. 


Chapter 14: Expanded Memory Systems 


Table 14-4. Functions of EMSPROCS.ASM 


SS sii SSPp 


Function Description 


EMSInst Returns flag indicating whether the EMM is installed in the system (A 
value of 0 indicates that the manager is present, a value of 1 is returned if 
the manager cannot be found.) 

EMSReady Returns a flag indicating whether the EMM and the expanded memory 
hardware are functional (A value of 0 indicates that the subsystem is us- 
able and ready, a value of 1 is returned if the subsystem should not be 
used. Use of this function assumes a previous successful call to EMSInst.) 

EMSPages Returns total number of expanded memory pages installed in the system 
(Use of this function assumes that the presence of the EMS driver and 
hardware has been established by previous successful calls to EMSInst 
and EMSReady.) 

EMSAvail Returns number of expanded memory pages currently available (Use of 
this function assumes that the presence of the EMS driver and hardware 
has been established by previous successful calls to EMSInst and EM- 
SReady.) 

EMSAlloc Allocates expanded memory pages and returns an EMM handle that can 
be used for subsequent mapping of those pages (If the pages cannot be al- 
located, 1 is returned. Use of this function assumes that the presence of 
the EMS driver and hardware has been established by previous successful 
calls to EMSInst and EMSReady.) 

EMSMap Called with an EMM handle, a logical expanded memory page number, 
and physical page number within the page frame (0-3) (It maps a pre- 
viously allocated expanded memory page to the requested physical page 
within the page frame, returning a far pointer to the mapped page.) 

EMSFree Called with an EMM handle and releases the previously allocated EMM 
pages. 

a a ee eee 


The subroutine package, Listing 14-1, can be assembled with the command: 
MASM /Mx EMSPROCS. The /Mx switch must be included so that the function names 
are not folded to uppercase (failure to use the /Mx switch will result in “unre- 
solved” messages when you attempt to link the package to a C program). The 
assembly language code shown for these procedures assumes that the C pro- 
grams which call it are being compiled as small model programs, but should be 
easy to convert for use with other memory models or high level languages. 


Listing 14-1. _EMSPROCS 
a es 


name emsprocs 
page 55,132 
title EMS support functions for C 


; 
; Expanded memory support functions for Microsoft C 
continued 
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Copyright © 1987 Ray Duncan 


To assemble: MASM /Mx /Zi EMSPROCS; 


=e ee Me hlUe hl 


args equ 4 ; offset of arguments, small model 
emm_int equ 67h : expanded memory manager interrupt 
DGROUP group  —_DATA : automatic data group 


_DATA segment word public ‘DATA’ 


public _emserr 


_emserr dw 0 : status from Last EMS operation 
emmname db " EMMXXXX0' s logical device name for EMM 
emframe dw 0 : segment of EMS page frame 
_DATA ~~ ends 


_TEXT segment word public ‘CODE’ 
assume cs:_TEXT,ds:_DATA 
public _EMSInst,_EMSReady 
public _EMSPages,_EMSAvail 
public _EMSALlLoc,_EMSMap, _EMSFree 


status = EMSInst(); 


status is 0 if expanded memory manager is present, 1 if not. 


=e Sse Be Me BO 


_EMSInst proc near 


push bp ; establish stack frame, 
mov bp,sp : save register variables 
push di 

push si 


continued 


mov _emserr,O 
mov al,emm_int 
mov ah,35h 

int 2th 

mov di,10 

mov si,offset DGROUP 
mov cx,8 

cld 

repz cmpsb 

mov ax,0 

jz _EMSInst1 
inc ax 


_EMSInst1: 


pop si 
pop di 
pop bp 
ret 


_EMSInst endp 


Status = EMSReady(); 


=e =e me me =e 


_EMSReady proc near 


push bp 
mov bp, sp 
push di 
push si 


mov ah, 40h 
int emm_int 


xchg ah,al 


me eo @e We =e =a 60 l6ULMlUO CUM 


me me =e me 


=e =e 
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initialize EMS error status 


fetch contents of 

EMM interrupt vector... 

AL = EMM int. number 

fxn 35H = get vector 
transfer to MS-DOS 

ES:DI = presumed addr. of 
name field in device header 
DS:SI = guaranteed EMM name 
emmname 

length of name field 


compare names... 

assume return false flag 
jump if driver present 
else return true flag 


restore register variables 
and return to C program 


status is 0 if EMS subsystem operational, 1 if not 


establish stack frame, 
save register variables 


call EMM to get status 


fix up status and save it 


continued 
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and ax, Offh s and set Zero flag 
mov _emserr,ax 
mov ax,0 assume returning false flag 


jz _EMSReady1 
inc ax 


jump if status ok 
otherwise return true flag 


~e =e We 


_EMSReady1: 


pop si s restore register variables 
pop di s and return to C program 
pop bp 

ret 


_EMSReady endp 


pages = EMSPages(); 


returns number of expanded memory pages installed in the system, 
returns O pages if operation failed. 


=e @e Sse BSE me =m. 


_EMSPages proc near 


push bp s establish stack frame, 
mov bp,sp 3 save register variables 
push di 

push si 


mov ah, 42h 
int emm_int 


call EMM to get total pages 


xchg ah,al fix up status and save it 


=e =e. 


and ax ,Offh and set Zero flag 

mov _emserr ,ax 

mov ax,0 s assume returning zero pages 
jnz _EMSPages1 ; jump if bad status 

mov ax, dx ; otherwise return total pages 


_EMSPages1: 
pop si 
pop di 


restore register variables 
and return to C program 


; 
; 
continued 
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pop 
ret 


bp 


_EMSPages endp 


=e 0 @*e8 Ge Ge BO 


pages = EMSAvail(); 


_EMSAvail proc near 


push 
mov 

push 
push 


mov 
int 


xchg 
and 
mov 


mov 
jnz 
mov 


_EMSAvail1: 
pop 
pop 
pop 
ret 


bp 
bp, sp 
di 
si 


ah, 42h 
emm_int 


ah,al 
ax ,Offh 
_emserr ,ax 


ax,0 
_EMSAvai 1 
ax, bx 


si 
di 
bp 


_EMSAvail endp 


ee Se S02 Ge we 


EMM_handle 


= EMSAL loc (pages); 


_EMSALloc proc near 
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returns the number of expanded memory pages currently available, 
returns 0 pages if operation failed. 


establish stack frame, 
save register variables 


=e 6} 


call EMM to get available pages 


=e 


fix up status and save it 
and set Zero flag 


assume returning zero pages 
jump if bad status 
otherwise return available pages 


restore register variables 
and return to C program 


EMM_handle is -1 if pages could not be allocated 


continued 
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push bp ; establish stack frame, 
mov bp,sp 5 save register variables 
push di 

push si 


mov ah, 4th 
int emm_int 
xchg ah,al 

and ax,Offh 


first get page frame segment, 
we'll need it for mapping calls 
fix up status and save it 

and set Zero flag 


=e ©e 6M UF 


mov _emserr,ax 

mov ax,~1 s assume returning -1 signal 
jnz _EMSALloc1 ; jump if bad status 

mov emframe,bx s else save page frame address 
mov bx, [bptargs] s; attempt to allocate pages 
mov ah, 43h 

int emm_int 


xchg ah,al 
and ax ,Offh 


fix up status and save it 
and set Zero flag 


=e =a 


mov _emserr,ax 
mov ax,71 5 assume returning -1 signal 
jnz _EMSALLoc1 ; jump if bad status 
mov ax, dx ; otherwise return EMM handle 
_EMSAL Loc’: 
pop $i ; restore register variables 
pop di : and return to C program 
pop bp 
ret 


_EMSALLoc endp 


char far *pageptr = EMSMap(EMM_handLle, logical_page,physical_page) 


maps the requested logical expanded memory page into the 

specified physical page, and returns a far pointer to the 

physical page, or a NULL pointer if the mapping failed. 
continued 


=e es se Se Be WO 
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° 
’ 


_EMSMap proc 


push 
mov 

push 
push 


mov 
mov 
mov 
mov 
int 
xchg 
and 
mov 
jnz 


mov 
mov 
mul 
mov 


jmp 


_EMSMap1: 
mov 
mov 


_EMSMape: 
pop 
pop 
pop 
ret 


_EMSMap endp 


=e =e 8 6M lM 


_EMSFree proc 


near 


bp 
bp, sp 
di 
$i 


dx, (bptargs] 
bx, [bptargst+2] 
ax, [bptargs+4] 
ah, 44h 

emm_int 

ah,al 

ax,Offh 
_emserr, ax 
_EMSMap1 


ax, [bptargs+4] 
dx ,4000h 

dx 

dx,emframe 
_EMSMap2 


dx,0 
ax,0 


$i 
di 
bp 


status = EMSFree(EMM_handle); 


near 


=e 6%e 


7) me me 


=e Se 6% 


me 


=e we @s BF Be BO 


=e =e 
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establish stack frame, 
save register variables 


EMM handle 
Logical page 
physical page 


request mapping 
fix up status and save it 
and set Zero flag 


bad status, return NULL ptr 


mapping OK, calculate pointer 
get physical page again 

multiply it by 16 KB 

to set AX = offset in page frame 
get segment of page frame 

and return far pointer 


if error, return NULL pointer 


restore register variables 
and return to C program 


status is 0 if pages deallocated successfully, 1 otherwise. 


continued 
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push bp s establish stack frame, 

mov bp, sp s save register variables 
push di 

push si 

mov dx, [op+args) $ get EMM handle 

mov ah, 45h 3; and try to release it 

int emm_int 

xchg ah,al ; fix up status and save it 
and ax ,Offh 3; and set Zero flag 

mov _emserr,ax 

mov ax,0 3; assume returning false flag 
jz _EMSFreet : jump if status was ok 

inc ax 3; otherwise return true flag 


_EMSFree1: 


pop si ; restore register variables 
pop di ; and return to C program 
pop bp 

ret 


_EMSFree endp 


_TEXT = ends 


end 


Finally, we will present a brief C program EMSDEMO.C, Listing 14-2, that dem- 
onstrates use of some of the EMS access subroutines. EMSDEMO.C can be compiled 
into the file EMSDEMO.OBJ and then linked with EMSPROCS.0BJ to form the execut- 
able file EMSDEMO. EXE with the following command line (for Microsoft C): CL EM- 
SDEMO.C EMSPROCS. 


Listing 14-2. EMSDEMO.C 


/* 
EMSDEMO.C Demonstrate use of EMS support 
functions in EMSPROCS.ASM 
continued 
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*/ 


Ray Duncan, August 1987 
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To compile and Link to EMSPROCS, with CodeView info: 


MASM /Mx /Zi EMSPROCS; 


CL /Zi EMSDEMO.C EMSPROCS 


Hinclude <stdio.h> 


extern 
extern 
extern 
extern 
extern 
extern 
extern 


extern 


static 


unsigned EMSInst(); 
unsigned EMSReady(); 
unsigned EMSPages(); 
unsigned EMSAvail(); 


/* prototypes for EMS functions */ 
/* provided by EMSPROCS.ASM */ 


unsigned EMSAL Loc (unsigned) ; 
char far *EMSMap(unsigned, unsigned, unsigned); 
unsigned EMSFree(unsigned) ; 


int emserr; 


char *ErrorMsg[) = ¢ 


mainCargc, argv) 


int 
cha 


argc; 
r *argv{]; 


/* contains status of most recent 
expanded memory operation */ 


"EMM internal error", 

"EMS hardware malfunction", 
"Memory manager busy", 

"Invalid EMM handle", 

"Function not defined", 

"Out of EMM handles", 

"Mapping context error", 
"Insufficient pages installed", 
"Insufficient pages available", 
"Zero pages allocation error", 
"Invalid logical page number", 
"Invalid physical page number", 
"Context save area full", 
"Duplicate context save", 
"Context restore not found", 
"Subfunction parameter undefined" }; 


continued 
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{ int status,handle; /* miscellaneous variables */ 
char far *pageptr; /* far pointer for mapped page */ 


puts(''\nSimple Demo Program for EMSPROCS"'); 


if€ EMSInst() ) /* test if EMM is installed in system */ 
{  puts('"\nExpanded memory manager not found''); 

exit (1); 
} 
if(€ EMSReady() ) /* if installed, make sure it is ready 

*/ 

{  puts(''\nExpanded memory manager not ready"); 

DisplayError(); 
} 
status = EMSPages(); /* report total pages in system */ 
printf('"\nExpanded memory pages installed = %d'"', status); 
DisplayError(); 
status = EMSAvail(); /* report pages not yet allocated */ 
printf(''\nExpanded memory pages available = %d\n", status); 
DisplayError(); 
handle = EMSALLoc(3); /* allocate some expanded memory */ 
printf("\nAl locating 3 pages, handle returned = %xh", handle); 
DisplayError(; 


/* demonstrate page mapping */ 
pageptr = EMSMapC(handle,2,3); 
puts ('\n\nMapping logical page 2 to physical page 3,"); 
printf("Page pointer = %lxh", pageptr); 


DisplayError(); 
Status=EMSFreeChandle); /* now release our pages */ 
puts (""\n\nDeallocating pages"); 
DisplayError(); 
exit (0); 
} 
DisplayError() /* show EMM error no. & message */ 


{ ifCemserr) 
continued 
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{ printf ('\nEMS error: %xh, %s", emserr, ErrorMsglemserr&0x7f]); 


exit (1); 
+ 
} 
Reading List 

t= The Lotus/Intel/Microsoft Expanded Memory Specification version 3.2 
(part no. 300275-003) or Expanded Memory Specification version 4.0 
(part no. 300686-001) can be obtained from Intel Corp.; 3065 Bowers 
Ave.; Santa Clara, CA 95051. 

t= The AST Enhanced Expanded Memory Specification can be obtained by 
writing to Product Marketing, AST Research; 2121 Alton Ave.; Irvine, Cali- 
fornia 92714. 

> 


The following are representative products that support LIM EMS and/or 
AOA EEMS. 


Spreadsheets: 

Lotus Development Corp. 1-2-3 
Javelin Software. Javelin 

Computer Associates. SuperCalc 
Lifetree Software. Words & Figures 
Daybreak Technologies. Silk 


Databases: 

Ansa. Paradox 

Borland International. Reflex 
Information Builders. PC/Focus 

Software Publishing. Pfs:Professional File 
Software Solutions. DataEase 


Symantec. O&A 


Integrated Products: 
Ashton-Tate. Framework II 


Lotus Development Corp. Symphony 
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Innovative Software. Smart 


CAD: 
Autodesk. AutoCAD 
T&W Systems. VersaCAD 


Program Managers and Operating Systems: 
Microsoft. Windows 

Quarterdeck Systems. DESQview 

Digital Research. Concurrent PC-DOS 
Softlogic Solutions. Software Carousel 


Utilities: 

Bourbaki Inc. 1DIR + 

Living Videotext Ready! and ThinkTank 
Multisoft. Super PC Kwik 

PC Support Group. Lightning 

Phoenix Technology. PDisk 

Polytron. PolyBoost and PolyDesk III 


Software Masters. Flash 


Ray Duncan is the author of Advanced MS-DOS (Microsoft Press 1986) and numer- 
ous articles and columns in Dr. Dobb’s Journal and other publications. Ray is founder 
of Laboratory Microsystems Inc., a software house specializing in Forth interpreters 
and compilers. 
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544 
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221 
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Ancient system call, 151 
AND operator, 119-120 
Andante tempo with SOUND driver, 352 
ANSL.SYS console driver, 30 
replacement for, 76 
APPEND command, 13 
Application programs 
batch file calling by, 17 
data access by, 220 
INT 21H for, 306, 310-312, 321-323 
interface for, 305~306 
and MS-DOS, 21-29 
AQA EEMS, 536, 539, 547 
Arc file tool (PCnix), 81 
Archiver, 81 
Arithmetic with EBL, 96 
Arrow keys with keydo.com program, 62 


ASCII code 
conversion of bytes and words to, 181-182 
and data communications, 477-478 
window messages for, 247 
ASSIGN program, 189-191, 208-209 
Assignments with EBL, 96 
Asterisks (*) 
in EBL, 96, 98 
as wildcards and metacharacters, 86-87 
Asynchronous data communications, 477-484 
At sign character (@) 
with batch echoing, 59 
with VC, 105 
Atget function (VC), 102-103 
Atsay function (VC), 102 
Attributes 
character, 104 
device, 308-309, 329, 331 
file, 39 
Auto repeat, keyboard, 62 
AUTOEXEC.BAT file, 92-93 
in booting, 10 
passwords for, 225 
AUX, opening of, 331 
Auxiliary stack, 322 
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B+ trees, 107-112 

Background Process function, 197, 210, 336 

Background programs, 336-338 

Backslashes (\) in file paths, 18, 58-59, 71 

Bank-switching with expanded memory, 
536-537 

Base address of serial adapters, 484 
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Base page, 197 
Batch files, 17-18, 91-93 
ECHO commands in, 59-61 
and environment, 156-157 
for on-line help, 66-67 
for PCnix commands, 62-67 
Baud rate 
in data transfer, 478 
with serial adapter, 491 
Beats with SOUND driver, 352 
BEEP command (EBL), 96 
BEGIN/END command (EBL), 96 
BeginPaint function (Windows), 255, 267 
BEGSTACK/.END command (EBL), 96 
BEGTYPE/END command (EBL), 96 
BINARY device attribute, 331 
Binary files 
locating text strings in, 76 
phone transmission of, 84-85 
reading of, 329 
BIOS, 6-8 
for data access, 220 
for EGA, 437 
hardware access by, 29 
loading of, 312-313 
module for, 10 
for serial adapter, 490-491 
software interrupts with, 25-26 
BIOS function (EBL), 97 
BIOS parameter blocks and built-in drivers, 
313 
Bit-mapped graphics and transparent write 
mode, 329-330 
Bit maps, reading of, 460-461 
Bit-mask register, 447-448, 454, 456-459, 461 
Bit-oriented data structures with MASM, 
117-120 
Bit planes, 446-447 
Block devices, 308, 313-314, 316 
Block length in PSP, 150-151 
Block size, function for, 160-162 
Booting of MS-DOS, 8-11 
and device drivers, 312-321 
and DPB, 173 
sector for, 8, 312 
Borland International 
integrated programming environments by, 


Turbo languages, linking of files in, 13 
BREAK 

in data transfer, 480 

disabling of, 225 
Break flag and INT 21H, 322 
Break-out switch debugger, 147 
Bresenham's Algorithm with line drawing, 

451-452 

Buffers 


Buffers—cont 

flushing of, 177, 334 

for keyboard input, 335 

size of, with EBL, 95 

See also Cache; Circular buffers 
BUFFERS = command, 10, 92, 317 
Built-in device drivers, 10, 307 

and IBMDOS initialization, 313 
Busy flag, 170 
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compiling with, 436 
expanded memory interface for, 550-551 
forward declarations in, 42-43 
libraries for, 28-29, 100-105 
and PCnix, 85 
and Resource Compiler, 257 
system calls with, 77 
C-INDEX +, file access with, 108-110 
Cache 
blocks for, 314-317 
for file 1/O, 10 
pointer to, 171 
Cache Block list and block drivers, 313 
Calendar with PCnix, 73-74 
CALL command (batch), 17, 64 
CALL command (EBL), 95, 96 
CALL.PURGE function (EBL), 97 
Cassette _IO interrupt for TSRs, 214 
Cat command (UNIX) and p PCnix tool, 76 
CD (Color Display), 437 
CDS (Current Directory Structure), 304, 319 
CGA (Color Graphics Adapter), 437 
Ch command (PCnix), 64-65 
Chaining of programs, 158-159 
Char _out subroutine, 180 
Characters 
attributes of, 104 
devices for, 308 
I/O routines for, 334-336 
CheckMenultem function (Windows), 263 
Child process, creation of, 158-159 
Child windows, 248-250 
in Notepad, 259 
CHKDSK/V command and hidden files, 
223-224 
Chmed file tool (PCnix), 81 
Chn file tool (PCnix), 81-82 
CHRDEV driver attribute, 309 
CICS (Customer Information Control System), 
100 
Cipher systems, 229-230 
Circular buffers, 80, 359-361 
for serial adapter, 492, 498-499 


Circular buffers—cont 
for SOUND driver, 378-379 
Class routines for SOUND driver, 377 
Classes, window, 250-252 
Clear To Send signal, 482 
CLI instruction, 358 
Client rectangles, 247-248 
Clipping regions, 254, 267 
Clock 
with PCnix, 73-74 
pointer to, 171 
Clock devices 
header for, in List of Lists, 315 
and IBMDOS initialization, 313 
initialization of, 316 
Clock interrupt service routine for SOUND 
driver, 379-381 
Close file function, 220 
Closing of devices, 330-331 
CLS command (EBL), 96 
Clusters, 219 
Code macros, 129-136 
Code segments with interrupts, 26, 139 
Code systems for data protection, 227-229 
CodeView, 28 
with MASM, 140 
Color 
monitors for, 437-439 
palettes of, 468-472 
of pixels, 460-461 
and set/reset register, 454 
COLOR command (EBL), 96 
Color Display, 437 
Color Graphics Adapter, 437 
COM files 
using debug to create, 67-68 
PSP segment address for, 149 
structure of, 23 
COM1 
base port address of, 484 
and INS8250 IC, 357 
interrupt request for, 489 
COM2 
base port address of, 484 
interrupt request for, 489 
Combining of commands, 64-66 
COMMAND.COM file, 7-8 
for batch file subroutines, 64 
environment for, 158 
loading of, 10, 312 
operation of, 11-16 
Command lines 
editing of, 62 
parsing of, 13-15, 46-48 
in PSP, 152 
slashes in, 18, 58-59 
Command processor 
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Command processor—cont 
back door to, 179-180 
MS-DOS, 6 
Commands 
combining of, 64-66 
driver, 353 
EBL, 96-98 
renaming of, 63 
repeating of, 63 
user, processing of, 11-16 
Comments 
with EBL, 96, 98 
with SOUND driver, 353 
Commit File function, 177 
Communal declarations with MASM, 140 
Compatibility and BIOS, 29 
Compilation 
of SOUND driver, 376 
of whereis, 52 
Compressor, file, 81 
COMSPEC environment variable, 16, 155-156 
command for, 320 
CON, opening of, 331 
Configuration and CONFIG.SYS file, 8-11, 92 
in booting, 10 
and environment size, 157-158 
and installable device drivers, 30 
loading of, 312 
Console Device Drivers, pointer to, 171 
Console devices 
ANSI.SYS drivers for, 30 
handles for, 152-153 
header for, in List of Lists, 315 
and IBMDOS initialization, 313 
initialization of, 316 
INT 2AH for, 179 
Control-C 
checking for, 322, 335 
and expanded memory systems, 549 
and INT 23H, 338 
and PSP, 151 
Control characters, 477-478 
Control functions, EBL, 97 
Control-P, processing of, 335 
Control-Q, with asynchronous 
communications, 478, 482 
Control-S 
with asynchronous communications, 478, 
482 
with keyboard polling, 335 
Controller chips, EGA, 449 
Coordinates, window, 248, 253 
COPY command for sequential files, 107 
Copying of files with whereis, 39 
Coroutines, 361-363 
for SOUND driver, 378 
Cp command (UNIX), emulation of, 65-66 
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CP/M 
and PSPs, 149-151 
and TSRs, 187 
CRC (Cyclic Redundancy Check), 480-481 
Create PSP block function, 158-159 
CreateWindow function (Windows), 251-252 
CREF directive (MASM), 134 
Critical errors 
and background programs, 337-338 
and expanded memory systems, 549 
flag for, 322 
handlers for, 213, 330, 331 
Critical sections, handling of, 365-366 
Cross-reference listings with MASM, 134 
Cruz, Frank, Kermit protocol by, 84 
CTS (Clear To Send) signal, 482 
CURCLK driver attribute, 309, 313 
CURNUL driver attribute, 309 
Current Directory Structure, 304, 319 
Current drive, function for, 70 
Customer Information Control System, 100 
CW _USEDEFAULT message (Windows), 
262-263 
Cyclic Redundancy Check in data transfer, 
480-481 


D 


Dadd function (C-INDEX), 111 
Data communications of binary files, 84-85 
See also Serial ports 
Data Encryption Standard, 230-236 
Data entry with VC, 102-103 
Data macros, 126-129 
Data protection and encryption, 2 220 
hiding data, 221-224 
and MS-DOS data access, 219-220 
and MS-DOS loopholes, 237-238 
passwords for, 225-237 
unauthorized access, levels of, 217-219 
Data rotate register, EGA, 464-465 
Data segments with interrupts, 139 
Data structures. See Tables 
Data Transfer Area, 37~38, 323, 328 
Date 
and clock device header, 313 
on directories, 220 
in DTA buffer, 328 
function for, 84 
handling of, with whereis, 50-52 
DCB. See Device Control Blocks 
Dclose function (C-INDEX), 110 
Dcreate function (C-INDEX), 110 
Ddelete function (C-INDEX), 111-112 
Deadlocks and wait loops, 364 
Debug 


Debug—cont 
cautions for, 332 
for creating .COM files, 67-68 
for PSP examination, 149 
scripts with, 60-61 
Debugging 
break-out switch for, 147 
with CodeView, 28 
of drivers, 338-344 
of windows, 260 
.DEF window files, 269 
DefWindowProc function (Windows), 245, 
264-265 
Delete key 
with keydo.com program, 62 
with VC, 103 
Deletion of files 
and data protection, 218, 237-238 
function for, 220 
with whereis, 39 
DES (Data Encryption Standard), 230-236 
Desk accessories, TSR, 185 
Desq function (C-INDEX), 111 


DestroyWindow function (Windows), 245, 264 


Device contexts, 267 
Device Control Blocks, 10, 304, 314 
and device openings, 326 
listhead for, in List of Lists, 315 
Device coordinates, 253 
Device drivers, 29-30, 303-304, 307-310 
and background programs, 336-338 
in BIOS, 10 
and boot process, 312-321 
debugging of, 338-344 
DEVICE = command for, 30, 316 
and DOS tables, 304-307 
in DPB, 172 
and expanded memory, 549-550 
and FCBs and handles, 323-324 
and hardware interrupts, 343-344 
and INT 21H, 321-323 
routines for, 325-336 
and SFT, 324-325 
See also SOUND driver 
Device headers, 306-308, 313, 315 
for SOUND driver, 366-367 
Device Parameter Blocks, 171-177 
Dfind function (C-INDEX), 111 
Diagonal lines, program to draw, 444-445 
Dictionary code book systems, 227-228 
Diff text tool (PCnix), 75-76 
Direct access of hardware, 29 
Directives, EBL, 97 
Directories 
and DPB, 173 
entries in, 173, 219-220 
Is PCnix tool for, 82-84 


Directories—cont 
reading of, in open routines, 327 
renaming of, 82 
searching of, with whereis, 39, 44-46 
tree-structured, 35-36 
DIRINFO structure, 37-38, 40-41 
Discardable blocks, 256 
Disk devices 
information for, in DPB, 171-172 
initialization of, 316 
logical, 172-173, 189, 209 
in UNIX, 58 
Disk I/O 
buffer for, 317 
interrupt for, 336 
Disk organizer, 81 
Disk stack, 322 
Diskette _IO interrupt, 191 
Dispatch routine for device drivers, 309-310 
DispatchMessage function (Windows), 
243-244 
Display. See Screen display 
Display Output routine, 334-335 
Dog file tool (PCnix), 81 
Dopen function (C-INDEX), 110 
DOS 
data access by, 220 
loading of, 312 
for SOUND driver, 376 
variables for, function for, 171-172 
DOS _CRITICAL function, 196-197 
DOS Safe Interrupt, 178-179 
Dotted notes with SOUND driver, 351-352 
Down arrow key with VC, 103 
DPB (Device Parameter Blocks), 171-177 
Dread function (C-INDEX), 111 
DTA (Data Transfer Area), 37-38, 323, 328 
Du file tool (PCnix), 81 
Dummy functions, 169-170 
Dummy labels, with MASM, 132 
Dupdate function (C-INDEX), 112 
DUPKEY label (C-INDEX), 109 
Duplicate handles, function for, 177-178 
Duplicate PSP block function, 159 
Duration with SOUND driver, 351-352 


E 


EBL (Extended Batch Language), 18, 94-99 
ECD (Enhanced Color Display), 437-438 
ECHO command (batch), disabling, 59-61 
ECHO command (UNIX), xp PCnix tool for, 85 
Ed text tool (PCnix), 75 
Editing 

of character input, 334 

of command lines, 62 


Index 


Editing—cont 
with standard devices, 335 
EEMS (Enhanced Expanded Memory 
Specification), 31, 536-540 
EGA. See Enhanced Graphics Adapter 
Eline text tool (PCnix), 75-76 
ELSE directive (MASM), 129 
EM _GETSEL message (Windows), 252 
EMM (Expanded Memory Manager), 537-540 
EMS. See Expanded memory systems 
Encryption, data, 227-237 
End of Interrupt instruction, 343, 489-490 
End key 
with keydo.com program, 62 
with VC, 103 
Endline.c program, 79 
ENDM directive (MASM), 127 
Enhanced Color Display, 437-438 
Enhanced Expanded Memory Specification, 
31, 536-540 
Enhanced Graphics Adapter, 435-440 
bit maps with, 460-461 
checking for, 440-443 
line drawing with, 451-454 
memory in, 446-449, 455, 457 
palettes for, 468-472 
print screen routine for, 461-468 
set/reset register in, 454-455 
speeding up of, 473-474 
write modes for, 455-459 
write-only register in, 450-451 
Environments 
and PSP, 22, 151 
segment for, 156-158 
setting of, 92-94 
EOI (end of interrupt) instruction, 343, 
489-490 
Epson printers, print screen routine for, 
465-468 
Equ directive (MASM), 134 
EQUAL parameter with C-INDEX, 111 
Equal sign (=) 
with MASM, 134 
with SOUND driver, 351 
Errors and error codes 
with C-INDEX, 110 
in data transfer, 480-482 
for device drivers, 339 
with EBL, 97-98 
with expanded memory systems, 543 
and read and write routines, 329 
ESC key with VC, 103 
Even parity in data transfer, 480 
Events, window, 245-247 
Exclamation point (!) with SOUND driver, 353 
EXE files 
PSP segment address for, 149 
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EXE files—cont 
structure of, 23-24 
EXEC function 
and batch files, 17 
for program loading, 22 
Execution of programs, 15-16 
EXIT command (EBL), 96 
Exit routine (MS-DOS) and PSP, 151 
Expanded memory systems, 31, 535-538 
C interface to, 550-551 
control with, 542-550 
EEMS, 536 
Expanded Memory Manager for, 537-540 
LIM, 535-536, 539, 547 
testing for, 540-542 
EXPORTS lists, 269 
Expression operator, MASM, 128 
Extended Batch Language, 18, 94-99 
Extended memory compared to expanded, 
538 
Extensions in directories, 220 


F 


FAT. See File Allocation Table 
Fatal Error routine and PSP, 151 
FCB. See File Control Blocks 
FCB = command, 317 
Ffind file tool (PCnix), 81 
FHT (File Handle Table), 151 
Fields 
bit, 119-120 
with VC, 102-104 
FIFO buffers, 492, 498-499 
File Allocation Table 
and cache blocks, 315 
for clusters, 219 
and DPB, 173 
and file deletion, 237 
and PCnix mv command, 82 
File Control Blocks, 26-27 
access routine with, 328 
close routine with, 330-331 
and device drivers, 323-324 
open routine with, 327 
in PSP, 152 
and SFT, 324-325 
File Handle Table, 151 
File handles, 152-155 
duplication of, 177-178 
and PSP, 151, 197 
Filecopy.c program, 77-78 
Filenames 
with commands, 15 
in directories, 220 
limitation of, 19 


Filenames—cont 

nonstandard, for hiding data, 221 
Files, 18-20 

access of, with PSP, 152 

attributes for, 39 

batch. See Batch files 

binary. See Binary files 

closing of, 330 

copying of, 39 

deletion of, and data protection, 237-238 

with EBL, 97 

EXE, 23-24, 149 

FCBs for, 26-27 

handles for. See File handles 

include, 40, 125-126 

key access systems for, 107-112 

linking of, 13 

listing of, 310-312 

names for. See Filenames 

opening of, 220, 540 

options with, 38-39 

password protection of, 226-227 

PCnix tools for, 81-84 

random, 107, 328 

sequential, 107, 328 

size of, on directories, 220 

system, 7-8 

tree-structured, 18-20 

See also Whereis directory search program 
FILES = command, 92, 153 
Filling of rectangle, program for, 456-457 
Filter for SOUND driver, 373 
Filter programs, 14 
FIND commands in MS-DOS vs. UNIX, 20 
FindResource function (Windows), 257 
Finite state machines, 363-364 

for SOUND driver, 376-378 
Flats for SOUND driver, 350-351 
Flushing of buffers, 177, 334 
Folders in graphic environments, 19 
FOR command with batch files, 17 
Formatting 

of hard disks, for data protection, 238 

of input, with VC, 103 
Forward declarations with C, 42-43 
Fragmentation 

of hard drives, program for, 81 

of memory, and windows, 255-256 
Free Memory function, 160-161 
Frequency generator for SOUND driver, 373 
Full duplex 

in data transfer, 482 

with serial adapter, 491 
Function 02H, 330, 334-335 
Function 0AH, 329, 335 
Function OBH, 131 
Function 17H, 82 


Function 19H, 70 
Function 1DH, 170 
Function 1EH, 170 
Function 1FH, 177 
Function 20H, 170 
Function 25H, 137, 489 
Function 26H, 158-159 
Function 2AH, 84 
Function 2CH, 84 
Function 31H, 25, 61, 194 
Function 32H, 177 
Function 33H, 321, 338 
Function 34H, 170, 179, 196, 322, 337 
Function 35H, 137, 489, 541 
Function 37H, 59, 170 
Function 3DH, 220, 540 
Function 3EH, 220, 540 
Function 3FH, 154, 220 
Function 40H, 153-154, 220 
Function 41H, 220 
Function 42H, 220 
Function 44H, 331, 540 
Function 45H, 177-178 
Function 46H, 177-178 
Function 48H, 160-161 
Function 49H, 160-161 
Function 4AH, 160-162 
Function 4BH, 151, 162, 179 
Function 4CH, 150 
Function 4EH, 37 
Function 4FH, 37 
Function 50H, 159-160, 197, 321, 338 
Function 51H, 159-160, 321, 337 
Function 52H, 163, 171-172 
Function 55H, 159 
Function 56H, 82 
Function 57H, 84 
Function 62H, 159-160, 321, 337 
Function 68H, 177 
Functions 
dispatcher of, 22 
for whereis, 41-42 
window, 242 
See also specific functions 


G 


Gersbach, J., keydo.com program by, 62 

Get Device Attributes, 331, 540 

Get DOS Variables function, 171-172 

Get _ega _info function, 440 

Get EMM Version function (EMM), 544 

Get Expanded Memory Pages function (EMM), 
544 

Get Input Status, 334 

Get Manager Status function (EMM), 543 


Index 


Get MS-DOS Busy Flag function, 170 
Get Number of EMM Handles function (EMM), 
545 
Get Output Status, 334 
Get Page Frame Segment function (EMM), 543 
Get Pages for All Handles function (EMM), 545 
Get Pages Owned by Handle function (EMM), 
545 
Get Physical Window Array function (EMM), 
546 
Get PSP function, 321 
Get/set/check break state function, 321 
Get/Set Page Map function (EMM), 545-546 
Get/Set Switch Char function, 170 
GET USER _PSP function, 197-198 
GetClassLong function (Windows), 267 
GetClassWord function (Windows), 267 
GetDC function (Windows), 267 
Getenv function, 156 
GetInstance function (Windows), 262 
GetMessage function (Windows), 243-244, 261 
GetSysColor function (Windows), 267 
GetTextMetrics function (Windows), 253 
GetWindowLong function (Windows), 267 
GetWindowWord function (Windows), 267 
Global filenames, C, tglob PCnix program for, 
85 
Global list. See List of lists 
Global options with MASM, 133 
GlobalAlloc function (Windows), 255-256 
GlobalLock function (Windows), 255, 268 
GlobalUnlock function (Windows), 255, 268 
GOTO command (EBL), 96 
Grammars for finite state machines, 363 
Graph in a Box, 186 
Graphic interfaces, folders in, 19 
GRAPHICS (TSR program), 189, 191 
and INT 05H, 198 
Graphics with windows, 252-255 
GREAT parameter (C-INDEX), 111 
GREATEQ parameter (C-INDEX), 111 
Greater than sign (>) 
with EBL, 97 
with IRP directive, 135 
for redirection, 14 
Grep text tool (PCnix), 75-76 


H 


Half duplex in data transfer, 482 
Handles 
access routine with, 328 
close routine with, 330 
and device drivers, 323-324 
duplication of, function for, 177-178 
file. See File handles 
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Handles—cont 
instance, 261 
open routine with, 326 
window, 243, 255 
Hard drives 
formatting of, for data protection, 238 
organizer for, 81 
Hardware interrupts, 136 
and device drivers, 343-344 
kernel access by, 25-26 
keyboard, and TSBs, 213-214 
Hashing with random files, 107 
Headers 
device, 306-308, 313, 315, 366-368 
for EXE programs, 23 
Heap manager with windows, 255-256 
Help screens, 105-106 
batch files for, 66-67 
HELPGEN.EXE program (VC), 106 
Hex _to ascii subroutine, 181 
Hexb _to_ascii subroutine, 181-182 


HIDDEN attribute for hiding data, 221-224 


Hierarchical files ,18-20. See also Whereis 
directory search program 
Home key 
with keydo.com program, 62 
with VC, 103 
Horton, Mark, programs by, 84-85 
Hyphen (-) 
for command options, 18, 58-59, 71 
with SOUND driver, 350 


I 


IBMBIO.COM file, 7-8, 312-313 
IBMDOS.COM file, 7-8, 312-316 
IF command with batch files, 17 
IF/THEN . . . ELSE command (EBL), 96 
IFE directive (MASM), 129 
IFIDN directive (MASM), 132 
IFNB directive (MASM), 132 
IN instruction, 357 
IN_DOS function, 196-197 
Include files 
with MASM, 125-126 
for whereis, 40 
Index sequential files, 107 
Indexes for help files, 106 
INDOS flag, 211 
and background programs, 337 
and INT 21H, 321-322 
Inheritance with devices, 331 
INKEY command (EBL), 96 
Inp function, 501 
Input editing with character I/O, 334 
Input focus with windows, 247 


INS8250 UART IC, 357 
Insert key with VC, 103 
Installable device drivers, 30, 307 
in CONFIG.SYS file, 10 
See also Device drivers 
Instance handles, 261 
Instant Recall, 186 
Instruction pointer and interrupts, 26 
INT 05H, 198-199 
INT 09H, 213-214 
INT 10H, 26, 336, 437 
Function OCH, 444 
Function 10H, 469-472 
Function 12H, 440 
INT 13H, 191, 220, 336, 337 
INT 14H, 490-491 
INT 15H, 214 
INT 16H, 214 
INT 19H, 312 
INT 1CH, 210-211, 336-337 
INT 20H, 150 
INT 21H (general dispatcher), 26 
for applications, 306, 310-312, 321-323 
and ASSIGN, 209 
for device drivers, 321-322, 329-330, 
334-335, 337-338 
for directories, 37, 82 
for files, 84, 220 
for handles, 153-154, 177-178 
for JFT size, 324 
for keyboard, 131 
for List of Lists location, 315 
for opening devices, 326 
and passwords, 226 
and PSPs, 150-152, 158-163, 197-198 
for switch character, 59, 170 
for TSRs, 25, 61, 194, 196-197 
undocumented, 170-172 
See also specific functions 
INT 22H, 22, 151, 194 
INT 23H, 151, 194, 322, 335, 338, 549 
INT 24H, 151, 194, 338, 549 
INT 25H, 37, 209, 336, 337 
INT 26H, 209, 336, 337 
INT 27H, 193-194 
INT 28H, 159, 178-179, 197, 210, 336-337 
INT 29H, 335 
INT 2AH, 179 
INT 2EH, 179-180 
INT 2FH, 194-196, 209, 327 
Int 4BH, 22 
INT 4CH, 67 
INT 67H, 539, 541-549 
Int86 functions, 501 
Intdos function, system date, 51 
Intdosx functions, 501 


Integrated programming environments, 28, 
113 

Intel 8250 UART, 484-492 
Intel 8253-5 programmable timer, 373-375 
Intel 8259A PIC chip, 489-490 
Interfaces 

for device drivers, 306-307 

uniform, 28 

user, 20~21, 241 
Internal commands 

COMMAND.COM, 12 

for devices, 327, 329-330 
Interrupt Controller (8259), 358, 375 
Interrupt enable register, UART, 484-485, 488 
Interrupt entry for SOUND driver, 376 
Interrupt identification register, UART, 

484-485, 488 

Interrupt requests, UART, 489 
Interrupt Vector Table, 26, 62, 191-192, 306 
Interrupts, 62 

with applications, 305-306 

and COM1, 357-359 

for device drivers, 308-309 

for expanded memory, 540-546 

handlers for, 44, 136-139, 499-501 

INT instruction for, 26, 191 

for 1/0, 486-487 

kernel access by, 25-26 

problems with, 27 

for serial adapter, 487-488 

and TSRs, 25, 191-193 

undocumented, 178-182 

See also specific interrupts 
InvalidateRect function (Windows), 254 
InvalidateWindow function (Windows), 263 
IO.SYS file, 7-8 

loading of, 10 
IOCTL driver attribute, 309 
IOCTL requests, 331-334, 368, 540 
IRET instruction, 306 ’ 
IRP directive (MASM), 135-136 
IRQ (interrupt request), 489 
Isblank function (VC), 104 
IsDialog Message function (Windows), 244 


J 
JFT ob File Table), 324, 326 
and background programs, 338 
and closing of files, 330 
K 


K command (SOUND driver), 351 
/K directive (EBL), 97 


Index 


Keep Process function, 194-196 
Kegel, Dan, nansi.sys by, 75-76 
KERMIT file transfer protocol, 481-482 
Kermit tool (PCnix), 84 
Kernel, 6-8 

device driver support in, 303-304 

features of, 21-22 

interrupts for, 25-26 

and IOCTL requests, 331 

relocation of, by SYSINT, 10 
Key file access systems, 107-112 
Key signatures with SOUND driver, 351 
Key tape code book systems, 228-229 
Keyboard 

auto repeat with, 62 

buffered input of, 335 

function for, 131-132 

input by, with EBL, 96 

and INT 28H, 197 

interrupt request for, 489 

poll routine for, 335 

and shells, 11 

and TSRs, 186, 213-214 

with VC, 103-104 

window messages for, 246-247 
Keydo.com program, 62 
Kneller, D.G., make utility by, 84 
Korn shells (ksh), 18 


L 


L command (SOUND driver), 351-352 

/L directive (EBL), 97 

Labels, MASM, 132 

Large memory model for Microsoft C, 501 

LaserJet printer, print screen routine for, 
461-465 

LASTDRIVE in CONFIG:SYS file, 319 

LASTFIELD label (C-INDEX), 109-110 

Latch registers, EGA, 446-449, 458, 464 

Learning curves, 20-21 

LEAVE command (EBL), 96 

Left arrow key with VC, 103 

Legato mode with SOUND driver, 352-353 

Length command with SOUND driver, 
351-352 

LESS parameter (C-INDEX), 111 

Less than sign (<) 

with EBL, 97 
with IRP directive, 135 

LESSEQ parameter (C-INDEX), 111 

Libraries for C, 28-29, 100-105 

LIM expanded memory system, 535-536, 539, 
547 

Line control register, UART, 484-485 

Line-editing with standard devices, 335 
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Line feeds with debug, 60 
Line status register, UART, 484-485 
Lines, program to draw, 452-454 
Linked lists for DCBs, 10 
Linking of files, 13 
List of Lists, 10 

and device drivers, 313-316 

pointer to, 171 
LISTER.COM program, 310-312 
Loadable device drivers, 10, 30, 307 

See also Device drivers 
Loading of programs, 22 
LoadMenu function (Windows), 257 
LoadResource function (Windows), 257 
LoadString function (Windows), 257, 262 
Local area networks, C-INDEX with, 108 
LOCAL directive (MASM), 132 
Local memory management function, 256 
Local stacks for TSRs, 213 
Logical coordinates, 253 
Logical disk drives 

and ASSIGN, 189, 209 

in DPB, 172-173 
Logical operators, 119-120 
Loop functions, VC, 104 
Low-pass filter for SOUND driver, 373 
LParam parameter (Windows), 244 
Ls file tool (PCnix), 81-84 


M 


Macintosh, learning curves for, 20-21 
Macros 

code, 129-136 

data, 126-129 

for EGA, 449-450 

and ProKey, 186 

for SOUND driver, 377 

with whereis, 41-42 
Make tool (PCnix), 84 


MakeProclInstance function (Windows), 269 


Map-mask register, 448, 454, 457 
Map Memory function (EMM), 544, 546 
Map select register, EGA, 460 
Mapping modes, window, 253 
MARK in data transfer, 478 
MASK directive (MASM), 119 
MASM techniques 

code macros, 129-136 

data macros, 126-129 

include files, 125-126 

records, 117-120 

structures, 120-124 
MCB (Memory Control Block), 162-163 
MCGA, 437 
MD (Monochrome Display), 437-439 


MDA (Monochrome Display Adapter), 437-439 
MDI (Multiple Document Interface), 250 
Media descriptor byte in DPB, 173 
Memory 
allocation of, 22-24, 152, 160-169, 255-256 
configuration of, with SYSINT, 10 
in EGA, 446-449 
and PSP, 151-152 
with windows, 255-256 
See also Expanded memory systems 
Memory Control Blocks, 162-163 
Memory models for Microsoft C, 501 
Memory resident programs. See Terminate 
and Stay Resident programs 
Menus 
batch file generation of, 18 
benefits of, 93-94 
and child windows, 250 
disadvantages of, 241-242 
Messages, window, 242-248 
Metacharacters, UNIX, 86-87 
Microsoft and TSRs, 189-190 
Microsoft C, 28 
compiling with, 436 
for data transfer package, 501-502 
Microsoft Quick languages, linking of files in, 
13 
Microsoft Windows, 30, 241-242 
classes of, 250-252 
graphics with, 252-255 
learning curve with, 20 
memory management of, 255-256 
messages for, 242-248 
resources for, 256-257, 268-269 
SPY program for, 257-269 
styles of, 248-250 
Minus sign (— ) 
for command options, 18, 58-59, 71 
with SOUND driver, 350 
MKDIR command with PCnix, 72-73 
MKS Toolkit, 18 
ML command (SOUND driver), 352 
MM _TEXT message (Windows), 253 
MN command (SOUND driver), 352 
Modal dialog boxes, 264 
MODE program, 188 
Modeless dialog boxes, 264 
Modeless programs, 31 
Modeless user interfaces, 241 
Modems for data transfer, 482 
registers for, 484-485 
status interrupt for, 488 
Moderato tempo with SOUND driver, 352 
Modularity of MS-DOS, 6 
Module Definition Files, 269 
Monitors 
damaging of, 444 


Monitors—cont 

for EGA, 437-440 
Monochrome Display, 437-439 
Monochrome Display Adapter, 437-439 
Morris, G. Allen, Jr., dog program by, 81 
Mouse window messages, 245-246 
Move read/write pointer function, 220 
MS command (SOUND driver), 352 
MS (modem status) interrupt, 488 
MS-DOS, 5 

2.0 compared to 3.3, 7 

applications level of, 21-29 

hardware level with, 29-30 

learning curves for, 20-21 

structure of, 6-11 

user level of, 11~21 
MSDOS.SYS file, 7-8 

See also Kernel 
MSNet and network devices, 327 
Multilanguage programming, 28 
Multilayer data protection, 218-219 
Multiple Document Interface, 250 
Multiple programs, 25 
Multiple shells, 17-18 
Multiple structures with MASM, 123-124 
Multiplex Interrupt, 194-196, 209 
Multisync monitors, 438 
Multitasking 

expanded memory for, 535-536, 538 

and file handles, 154 

and Function 55H, 159 

operating system for, 27 

and PSP, 22, 152 

and TSRs, 189-190 

and UNIX, 57 

and VC, 104 
Multiuser systems, C-INDEX with, 108 
Musical notes, 349-350 

See also SOUND driver 
Mv file tool (PCnix), 81-82 


N 


N command (SOUND driver), 349 
%NAME% variable (EBL), 97 
Nansi.sys display driver, 75-76 


National Security Agency, DES approval by, 


230 
Naturals with SOUND driver, 351 
Nesting of macros, 131-133 
Network devices and open routines, 327 
NONIBM driver attribute, 309 
NONKEY label (C-INDEX), 109-110 


Nonstandard filenames for hiding data, 221 


NOT operator, 119-120 
Notepad, 259-260 


Index 


Notes (musical) with SOUND driver, 349-350 


Now tool (PCnix), 84-85 
NUL device 
driver for, in DPB, 172 
header for, 306, 313, 315 
writing to, 330 
Null characters in filenames, 221 
Number sign (#) 
with SOUND driver, 350 
for VC fields, 103 


O 


O command (SOUND driver), 349 
Object-oriented programming, 30-31 
OCRM driver attribute, 309, 327, 331 
Octaves with SOUND driver, 349-350 
Odd parity in data transfer, 480 
-ON.ERROR (EBL), 98 

On-line help, batch files for, 66-67 
Open file function, 220, 540 
Opening of devices, 326-327 


Option switches with COMMAND.COM, 14, 


18, 58-59 

with whereis, 38-39 
OR operator, 119-120 
OS/2, 31-32 

and windows, 270 
%OUT directive (MASM), 129 
OUT instruction, 357 

with EGA, 447 
Outline processor, TSR, 186 
Outp function, 501 

with EGA, 447, 473 
Outport function, 473 
Output logging with character I/O, 334 
Overlapped windows, 106, 248 
Overscan register, EGA, 469-470 


P 


P command (SOUND driver), 352 
/P directive (EBL), 95, 97 

P text tool (PCnix), 75-76 

Packets, data transfer of, 481-482 
Page frames, 538 


Painting of windows, 254-255, 267-268 


PaintWindow function (Windows), 267-268 


Palettes, 468-472 

Paragraphs, 151, 160-161 

Parallel data transfer, 478 
Parameter save area and EGA, 470 
Parent process, id for, in PSP, 151 
Parity in data transfer, 478, 480-482 
PARSE command (EBL), 96 
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Parsing 
of command-line options, 46-48 
of user commands, 11, 13-15 
Password protection, 225-237 
PATH environment variable, 13, 156 
Paths, 13 
for opening devices, 326 
separators for, 18, 58-59, 71 
setting of, 92-93 
PAUSE batch command, 95 
Pauses with SOUND driver, 352 
PC-DOS, 8, 187-188 
PCnix 
batch files for, 62-74 
with MS-DOS functions, 58-62 
tools for, 75-86 
and UNIX, 55-58 
and wildcards, 86-87 
Percent sign (%) 
for batch variables, 97, 156 
for expression operator, 128 
for UNIX prompt, 58 
Permanent part of COMMAND.COM, 15 
PgDn key with VC, 103 
PgUp key with VC, 103 
Physical security of data, 218 
PIC (Programmable Interrupt Controller) chip, 
489-490 
Piping, 14 
with batch files, 156 
with UNIX, 57 
Pitch (musical), 349-350 
Pixels 
addresses of, 451 
color of, 460-461 
height and width of, 454 
Placeholders with batch files, 17 
Plus sign (+) with SOUND driver, 350 
Polling of I/O, 486 
Popup windows, 248 
Port addresses, 484 
Portability 
and C, 100 
and device drivers, 307 
Ports, I/O, 490 
See also Serial ports 
POST. See Power On Self Test 
PostMessage function (Windows), 252 
PostQuitMessage function (Windows), 261 
Power On Self Test, 8, 312 
and passwords, 226 
and serial adapters, 490-491 
Pr text tool (PCnix), 75-76 
Predefined equates with MASM, 140 
Presto tempo with SOUND driver, 352 
PRINT:COM program 
and INT 21H, 337 


PRINT.COM program—cont 
and INT 28H, 179, 336 
and INT 2FH, 194 
as TSR, 188-189, 191, 210-211 
Print Screen key, disabling of, 198-208 
Print screen routine, 461-468 
Print Spooler Control interrupt, 194-196 
Printer and control-p, 335 
Printing of characters, subroutine for, 180 
PRN, opening of, 331 
Process Id in PSP, 151 
Program Segment Prefix, 148-152 
and background programs, 337 
command line in, 14 
construction of, 22 
functions for, 158-160 
JFT in, 324 
resources in, 304-305 
and TSRs, 197-198 
Programmable Interrupt Controller chip, 
489-490 
Programmable interval timer (8253-5) chip, 
373-375 
Programs 
execution of, 15-16 
loading of, 22 
multiple, 25 
object-oriented, 30-31 
structure of, 22-24 
termination of, 150 
ProKey, 186 
PROMPT environment variable, 156 
Prompts 
in booting, 10 
for PCnix, 58 
setting of, 93 
Protection, data. See Data protection and 
encryption 
PS/2, video adapters for, 437 
PSOFF program, 199-208 
PSP. See Program Segment Prefix 
Public key cryptosystems, 233-236 
Pushbuttons, window, 246 
Pwd file tool (PCnix), 81 


Q 


/Q directive (EBL), 97 
%Q variable (EBL), 97 
Qk.com program, 62 
Question marks (?) as wildcards and 
metacharacters, 86~87 
Queues 
for interrupt handler, 492 
with serial data transfer, 487 
for window messages, 243-244 


QuickBASIC, 28 
QuickC, 28 


R 


/R directive (EBL), 97 
%RK variable (EBL), 97 
RAM function (EBL), 97 
RAMdisk 
drivers for, 30 
with PCnix, 71-72 
Random files, 107, 328 
RC (Resource Compiler), 257 
RDA (receive data available) interrupt, 488 
READ command (EBL), 96 
Read Control Information, 333-334 
Read from file function, 220 
READ-ONLY attributes for hiding data, 224 
READ.PARSED command (EBL), 96 
Read sector function, 220 
Reading 
of data, unauthorized, 218 
of devices, 328-329 
READSCRN command (EBL), 96 
READSCRN.PARSED command (EBL), 96 
Ready outline processor, 186 
Receive buffer register, UART, 484-485 
Receive data available interrupt, 488 
Receive line status interrupt, 487-488 
Receive queues for data transfer, 487 
Records 
locking of, with C-INDEX, 108-109 
with MASM, 117-120 
Rectangles, window, 247-248, 253-254 
Recursive methods for directory searching, 
19, 36-37 
Redirection, 14 
and file handles, 153-154 
and Function 46H, 178 
and IBMDOS initialization, 313 
with MODE, 188 
Regions, window, 253-254 
RegisterClass function (Windows), 251-252, 
262, 267 
Registers, UART, 484 
Release Handle and Memory function (EMM), 
544 
ReleaseCapture function (Windows), 246 
Relocatability of EXE programs, 23 
Relocatable memory management with 
windows, 255 
Renaming 
of commands, 63 
of directories, 82 
Repeating 
of commands, 63 


Index 


Repeating—cont 
of keystrokes, 62 
REPT directive (MASM), 127 
Request headers 
and IBMDOS, 313 
for SOUND driver, 367-368 
Request To Send signal, 482 
Reserved functions, 169-170 
Resident part of COMMAND.COM, 15 
Resource Compiler, 257 
Resources, window, 256-257, 268-269 
Restore Mapping Context function (EMM), 545 
Rests with SOUND driver, 352 
RESUME (EBL), 98 
Ret variable (C-INDEX), 110 
Ret variable (VC), 106 
RETURN command (EBL), 96 
Right arrow key with VC, 103 
RLS (receive line status) interrupt, 487-488 
Rm command (UNIX), approximation of, 63 
Rollins, Dan, qk.com program by, 62 
Root directory, 219 
and DPB, 173 
RS-232-C data transfer standard, 482-484 
RSA cryptosystems, 234 
RTS (Request To Send) signal, 482 


S 


/S directive (EBL), 97 
%S variable (EBL), 97 
Save Mapping Context function (EMM), 
544-545 

Scales (musical) with SOUND driver, 350-351 
Scrambling of data, 227-237 
Screen display, 99-107 

dumping of, 189 

and INT 10H, 437 

memory for, 446-449 

printing of, 461-468 

programming of, 91 

and TSRs, 214 
Screen logging, 335 
ScrollWindow function (Windows), 265 
Search for First directory function, 37, 

545-546 

Search for Next directory function, 37 
Search paths, 13 
Seattle Computer Products, MS-DOS by, 187 
Sector size in DPB, 171, 173 
Security. See Data protection and encryption 
Semicolons (;) with MASM comments, 134 
SendMessage function (Windows), 252 
Sequencer chip, EGA, 448-449 
Sequential files, 107, 328 
Serial adapters, 484 
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Serial adapters—cont 
interrupts for, 487-488 
Serial ports 
and asynchronous data communications, 
477-484 
program using, 493-532 
and UART, 484-492 
SET command, 13, 155 
Set Current PSP function, 159 
Set Device Attributes, 331 
Set Palette routine, 469-472 
Set PSP function, 321 
Set/reset register, EGA, 454-455, 457 
SET USER _ PSP function, 197-198 
Setattr function (VC), 104 
SetCapture function (Windows), 246 
SETCLOCK programs, 190 
SETDTA macro (whereis), 38 
SetFocus function (Windows), 247 
Setloop function (VC), 105 
SetScrollPos function (Windows), 265 
SFN (System File Number), 324-326 
SFT. See System File Table 
Sharps for SOUND driver, 350-351 
Shells, 320 
commands for, 10, 96 
multiple, 17-18 
UNIX, 18 
See also COMMAND.COM file 
ShowWindow function (Windows), 261 
SideKick, 185 
SKIP command (EBL), 96 
Slashes (/) 
for command options, 18, 58-59 
with EBL commands, 97 
in file paths, 18, 58-59, 71 
Slurs with SOUND driver, 352 
Small memory model for Microsoft C, 501 
SmartKey, 186, 187 
Software interrupts 
kernel access by, 25-26 
and TSRs, 191-193 
See also specific interrupts 
SOUND driver 
DOS internals for, 366-368 
file creation for, 353-355 
finite state machine for, 376-378 
hardware for, 355-359, 373-375 
listing of, 385-431 
musical notation for, 349-353 
performance evaluation of, 381-382 
programming techniques for, 359-366 
prototype for, 369-373 
refinements for, 382-385 
setting up, 347-349 
SPACE in data transfer, 478 
SPECL driver attribute, 309 


Spelling checker, TSR, 186 
Split text tool (PCnix), 75 
Spoolers, TSR, 188-189 
Spotlight, 185 
SPY program for windows, 257-269 
Sr text tool (PCnix), 75 
Staccato mode with SOUND driver, 352-353 
STACK command (EBL), 96 
STACK.LIFO command (EBL), 96 
STACK.OFF function (EBL), 97 
STACK.ON function (EBL), 97 
STACK.PURGE function (EBL), 97 
Stack segment and PSP, 151 
Stacks 
with interrupts, 26, 138, 192-193, 213 
overflow of, with device drivers, 343 
switching of, with INT 21H, 322-323 
Standard auxiliary device with character I/O, 
334 
Standard error with character I/O, 334 
Standard I/O handles, 152 
Standard input 
with character I/O, 334 
devices for, 130, 335 
reading from, 329 
Standard interface, CICS as, 100 
Standard output 
with character I/O, 334 
devices for, 180 
writing to, 330, 334-335 
Standard printer with character I/O, 334 
START bit in data transfer, 478 
Startup, DOS, 8-11 
STATEOF command (EBL), 96 
States in finite state machines, 363 
STDIN driver attribute, 309, 313, 331 
#stdio.h file for C, 100 
STDOUT driver attribute, 309, 313, 331 
STI instruction, 358, 489 
STOP bit in data transfer, 478 
Str text tool (PCnix), 75 
Strategy routines for device drivers, 308-309, 
376 
STRING label (C-INDEX), 109 
String out subroutine, 180-181 
Strings, handling of, by EBL, 96 
Strings program (UNIX) and str PCnix tool, 76 
Structures 
with MASM, 120-124 
as subroutine parameters, 136 
Subdirectories, 219 
password protection of, 226-227 
Subroutines, 180-182 
in batch files, 157 
batch files as, 64 
coding of, as macros, 134 
compared to coroutines, 361 


Subroutines—cont 

compared to macros, 130 

parameters for, structures as, 136 
SUBST command with PCnix, 68-71 
Substitute operator (&), MASM, 127-128 
SuperKey, 186 
Switch tool (PCnix), 84-85 
SWITCHAR 

changing of, 59 

function for, 170 

with SUBST, 71 

switch PCnix program for, 85 
Synchronization 

of interrupts, 343 

of multiple processes, 364-365 

of SOUND driver, 378-379 
Synchronous data transfer, 478 
SYSINT module, 10 
System calls from C, 77 
System clock, speeding up of, 379-382 
System date, function to convert, 51 
System File Number, 324-326 
System File Table, 26-27, 152-153, 304 

aging of entries in, 327 

building of, 317-319 

and closing of devices, 330 

and device drivers, 324-326 

and IOCTL requests, 331 

pointer to, 171 

and read routine, 329 
System files, 7-8 
System kernel. See Kernel 
System timer, interrupt request for, 489 


T 


T command (SOUND driver), 352 
Tables, 26-27 

and device drivers, 304-307 

of files open, 171 

MS-DOS, building of, 10 
Tail text tool (PCnix), 75-77 
Task-switching, 25 
Tempo with SOUND driver, 352 
Temporary part of COMMAND.COM, 15 
Terminate and Stay Resident programs, 

185-186 

and busy flag, 170 

and expanded memory, 549-550 

function calls with, 61, 209-211 

guidelines for, 213-214 

interrupt for, 193-194 

and memory allocation, 23-25, 158 

origin of, 186-190 

PSP functions for, 159-160 

sample of, 198-208 


Index 


Terminate and Stay Resident programs—cont 
with UNIX-like shells, 56 
UNSPOOL program, 211-213 
well-behaved, 190-198 
Termination handler, 22, 151, 194 
TEST command (MASM), 119-120 
Text, PCnix tools for, 75-80 
Text mode, writing in, 330 
Tglob tool (PCnix), 84-85 
Thesaurus, TSR, 186 
THRE (transmit holding register empty) 
interrupt, 488 
Time 
and clock device header, 313 
on directories, 220 
in DTA buffer, 328 
function for, 84 
interrupts for, 336, 489 
Timer _Tick interrupt, 210-211 
Tokens for finite state machines, 363 
Toscreen.c program, 77 
Touch tool (PCnix), 84 
Tr text tool (PCnix), 75-76 
TRACE.OFF function (EBL), 97 
TRACE.ON function (EBL), 97 
Transitions in finite state machines, 363 
TranslateMessage function (Windows), 261 
Transmit holding register, UART, 484-485 
Transmit holding register empty interrupt, 
488 
Transmit queues for data transfer, 487 
Transparent write meade, 329 
Trapdoor functions, 234 
Tree command, 19 
Tree-structured files, 18-20 
See also Whereis directory search program 
TSR programs. See Terminate and Stay 
Resident programs 
Turbo C, compiling with, 436 
Turbo Lightning, 186 
Turbo Pascal, 28 
TYPE command (EBL), 96 
TYPE operator (MASM), 135 
-TYPE operator (MASM), 135 


U 


/U directive (EBL), 97 

UART (Universal Asynchronous Receiver 
Transmitter), 357, 484-492 

Uniform, 187 

Uniform interfaces, 28 

Unig text tool (PCnix), 75-76 

Universal Asynchronous Receiver Transmitter, 
357, 484-492 
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UNIX 
file path separators in, 18, 58-59 
learning curves for, 20-21 
shells for, 17 
See also PCnix 
UNSPOOL program, 187, 211-213 
Up arrow key with VC, 103 


UpdateWindow function (Windows), 266 


User interaction with EBL, 95 
User interface 

improving, 20-21 

modeless, 241 

See also Command processor 
User stack, 322 
Uudecode tool (PCnix), 84 
Uuencode tool (PCnix), 84 


V 


%V variable (EBL), 97 
Variables 
batch, with EBL, 96-98 
Dos, function for, 171-172 
in environment, 156-157 
VC (Vitamin C) library, 100-106 
VDISK.SYS driver, 30 
Vertical bar (|) 
with batch files, 156 
for piping, 14 
VGA (Video Graphics Array), 437 
Video and TSRs, 214 
Video Graphics Array, 437 
Video interrupt, 336, 437 


Video services, BIOS, interrupt for, 26 


Virtual windows with VC, 107 
Vitamin C library, 100-106 
VSAM files, 107 


w 


We text teol (PCnix), 75-76 
Well-behaved TSRs, 190-198 


Whereis directory search program, 35 


analysis of, 39-52 

compilation of, 52 

functions in, 37-38 

options in, 38-39 

using recursion, 36-37 
White, Nat, RAMdisk system by, 71 
Wildcards 

commands with, 15 
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Wildcards—cont 
compared to UNIX metacharacters, 86-87 
with directories, 19, 37 
Windows, creation of, with VC, 106-107 
See also Microsoft Windows 
WinMain function (Windows), 243, 261 
WM _ ACTIVATE message (Windows), 247 
WM _CHAR message (Windows), 247 
WM _CLOSE message (Windows), 245 
WM_COMMAND message (Windows), 263 
WM _DESTROY message (Windows), 264-265 
WM _HSCROLL message (Windows), 263, 265 
WM _KEYDOWN message (Windows), 
246-247, 266 
WM _KEYUP message (Windows), 246-247 
WM _KILLFOCUS message (Windows), 247 
WM _LBUTTONDOWN message (Windows), 
242, 246 
WM _LBUTTONUP message (Windows), 242, 
246 
WM __MOUSEMOVE message (Windows), 
245-246 
WM _NCFPAINT message (Windows), 245 
WM _PAINT message (Windows), 254-255, 
266 
WM _QUIT message (Windows), 261 
WM _SETFOCUS message (Windows), 247 
WM _ SIZE message (Windows), 266 
WM_SYSCOMMAND message (Windows), 
265 
WM _VSCROLL message (Windows), 263, 265 
Wordlength in data transfer, 478 
WordStar and p PCnix tool, 76 
WParam parameter (Windows), 244, 266 
Write Control] Information, 333-334 
Write Dot routine, 444 
Write modes, EGA, 455-459 
Write-only register, EGA, 450-451 
Write sector function, 220 
Write to file function, 220 
Writing to devices, 328-330 
Wselect function (VC), 106 


X 


Xatget function (VC), 104 

Xcopy command, 19 

.XCREF directive (MASM), 134 

XMODEM file transfer protocol, 481-482 
XON/XOFF data flow control, 478, 482-484 
XOR operator, 119 

Xp tool (PCnix), 84-85 


The Waite Group's 
MS-DOS Developer's Guide, 
Second Edition 
John Angermeyer, Kevin Jaeger, 
The Waite Group 


sanding upon the first edition, MS- 
S' Developer's Guide covers the MS 


| PC DOS operating systems, concen- 


ing on techniques for developing ap- 
ations programs. Ideally suited for 
grammers, developers, and “power 
rs,” the book highlights the specifics 
he operating system's internal 

avior which is so essential to 

em integration and software 
elopment. 


$ revised guide includes special em- 
sis on undocumented DOS functions 
well as coverage of MS-DOS file 
ctures and their differences. 


ics covered include: 


Tools for Structured Coding 

The Design and Implementation of 
Modular Programs 

rogram and Memory Management 
eal-Time Programming 

nstallable Device Drivers 

Writing Programs for the Intel 8087/ 
30287 Math Coprocessor 

sANs and MS-DOS 

Jisk Layout and File Recovery 
nformation 

tecovering Data Lost in Memory 
differences Between MS-DOS 
/ersions 

ligh-Level Languages 

Jebugging Techniques 

Aicrosoft Windows 

ippendices: Development Tools, 
tibliography, ASCII Cross-Reference 
nd Number Conversions, Product 
inhancements 


Pages, 7% x 9%, Softbound 
I: 0-672-22630-8 
22630, $24.95 


The Waite Group's 
Understanding MS-DOS® 
Kate O'Day and John Angermeyer, 

The Waite Group 


MS-DOS is a very powerful and intricate 
operating system with millions of users. 
This operating system can be explored 
by beginning programmers in a hands- 
on approach, at the keyboard. 


Understanding MS-DOS introduces the 
use and operation of this popular 
operating system for those with little 
previous experience in computer hard- 
ware or software. The fundamentals of 
the operating system such as EDLIN, 
tree-structured directories and 
pathnames, and such advanced features 
as redirection and filtering are presented 
in a way that is easy-to-understand and 
use. 


Topics covered include: 


@ Organizing Data into Files 

@ Redirecting Input and Output 

@ Using the Text Editor EDLIN to 
Create and Edit Files 

@ Using Commands to Manage Files 

@ Special Function Keys and Key 
Combinations 

@ Creating Batch Files of Often 
Repeated Commands 

@ Create and Use Tree Structured 
Directories 


300 Pages, 7 x 9, Softbound 
ISBN: 0-672-27067-6 
No. 27067, $17.95 


The Waite Group's 
Tricks of the MS-DOS® Masters 
John Angermeyer, Rich Fahringer, 
Kevin Jaeger, and Dan Shafer, 
The Waite Group 


This title provides the personal user 
(not necessarily the programmer or soft- 
ware developer) with a wealth of ad- 
vanced tips about the operating system 


and tricks for using it most successfully. 


Also included are advanced tips on us- 
ing popular software packages such as 
WordStar.® 


Topics covered include: 


@ Secrets of the Batch File Command 
Language 

@ Secrets of Pipes, Filters, and 
Redirection 

@ Secrets of Tree-Structured Directories 

@ Discovering Secrets: A Debugger 
Tutorial 

@ Secrets of DOS Commands 

@ Secrets of Files 

@ Secrets of Free and Low-Cost 
Software 

@ Secrets of Add-on Software, Boards, 
and Mass Storage 

@ Secrets of System Configuration 

@ Secrets of Data Encryption 


568 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22525-5 
No. 22525, $24.95 


The Waite Group's 
Discovering MS-DOS® 
Kate O'Day, The Waite Group 


This comprehensive study of MS-DOS 
commands such as DEBUG, LINK, and 
EDLIN begins with general information 
about operating systems. [It then shows 
how to use MS-DOS to produce letters 
and documents; create, name, and 
manipulate files; use the keyboard and 
function keys to perform jobs faster; 
and direct, sort, and find data quickly. 


It features a command summary card 
for quick reference. 


Topics covered include: 


@ Introduction to MS-DOS 

@ What is a Computer System? 

@ What is an Operating System? 

@ Getting MS-DOS off the Ground 

@ System Insurance 

@ Editing 

@ Filing 

@ Batch Files 

@ Paths 

@ Input/Output 

@ Hard Disks 

™ Appendices: Error Messages, 
Reference Card 


296 Pages, 7% x 934, Softbound 


ISBN: 0-672-22407-0 
No. 22407, $19.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 


MS-DOS® Bible, Second Edition 
Steven Simrin, The Waite Group 


This revised edition of the best seller is 
ideally targeted for the intermediate lev- 
el user and programmer of the operat- 
ing system, especially those who have 
upgraded to the new version 3.3. The 
comprehensive tutorial emphasizes the 
new features found in DOS 3.3 and pro- 
vides expanded coverage of batch files, 
device drivers, memory management, 
and network commands. 


The new expanded batch language, disk 
structure, terminate and stay resident 
programs (TSRs), and the Lotus-Intel ex- 
panded memory model 4.0 are high- 
lighted. The new commands are 
explained in detail, and a unique “Infor- 
mation Jump Table” is included and 
enhanced for easy reference. 


Topics covered include: 


@ Starting MS-DOS 

@ MS-DOS Files and Batch Files 

@ Directories, Paths, and Trees 

@ Installing a Fixed Disk 

@ Redirection, Filters, and Pipes 

@ EDLIN 

™@ Extended Keyboard and Display 
Control 

@ Debug 

B Link 

@ Disk Structure 

@ MS-DOS Device Drivers 

@ MS-DOS Commands 

& Appendices: Undocumented Features; 
MS-DOS Interrupts and Function 
Calls: Practical Batch Files; ASCII 
Cross Reference Table 


568 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22617-0 
No. 22617, $22.95 


Hard Disk Management , 
Techniques for the IBM 
Joseph-David Carrabis 


This is a resource book of in-depth 
techniques on how to set up and 
manage a hard disk environment 
directed to the everyday “power user,” 
not necessarily the DOS expert or 
programmer. 


Each fundamental technique, based on 
the author's consulting experience with 
Fortune 500 companies, is emphasized 
to help the reader become a “power 
user.” This tutorial highlights installa- 
tion of utilities, hardware, software, and 
software applications for the experienced 
business professional working with a 
hard disk drive. 


Topics covered include: 


@ Introduction to Hard Disks 

@ Hard Disks and DOS 

@ Backup and What You Need to 
Know 

@ Service and Maintenance 

@ Setting Up a Hard Disk 

@ Organizing a Hard Disk 

W Hard Disk Managers 

@ Utilities to Find Files, Get Overlays, 
unERAse Files, Recover Damaged 
Files, Speed Up Disk Access, and 
Restore and Backup Disks 

@ Maintenance Utilities 

@ File Security Utilities 

@ Security Utilities 

250 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22580-8 
No. 22580, $22.95 


IBM® PC AT 
User’s Reference Manual 
Gilbert Held 


Includes everything you need to know 
about operating your IBM PC AT—how 
to set the system up, write programs 
that fully use the AT’s power, organize 
fixed-disk directories, and use IBM's 
multitasking TopView. 


Includes a BASIC tutorial for beginners 
and includes several fixed disk 
organizer programs—all clearly de- 
scribed, explained, and illustrated. 


Topics covered include: 


@ Hardware Overview 

@ System Setup 

@ Storage Media and Keyboard 
Operation 

@ The Disk Operating System 

@ Fixed Disk Organization 

@ BASIC Overview 

@ Basic BASIC 

@ BASIC Commands 

@ Advanced BASIC 

B Data File Operation 

@ Text and Graphics Display Control 

@ Batch and Shell Processing 

@ Introduction to TopView 

@ Appendices: ASCH 
Code Representation, Extended 
Character Codes, BASIC Error 
Messages, Programming Tips and 
Techniques 

453 Pages, 7 x 9%, Softbound 


ISBN: 0-8104-6394-6 
No. 46394, $29.95 
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IBM® PC & PC XT User’s 
Reference Manual, 
Second Edition 
Gilbert Held 


Expanded to include the more powel 
PC XT, this second edition contains 
most up-to-date information available 
the IBM PC. From setup through ap 
ing and modifying the system, this | 
continues to provide users with clea 
step-by-step explanations of IBM PC 
hardware and software—complele w 
numerous illustrations and examples 


Highlights of the second edition inc’ 
instructions for using DOS 3.1 and 
upgrading a PC to an XT; informati 
on the customized hardware configu 
tion of the PC and XT; explanations 
how to load programs on a fixed di 
and how to organize directories; an 
material on available software, inch 
compilers. 


Topics covered include: 


@ Hardware Overview 

W System Setup 

Storage Media and Keyboard Op: 

@ The Disk Operating System 

@ Fixed Disk Organization 

@ BASIC Overview 

@ BASIC Commands 

@ Data File Operations 

@ Text and Graphics Display Cont 

@ Batch Processing and Fixed 
Disk Operations 

B® Audio and Data Communication 

@ Introduction to TopView 

@ Appendices: ASCII 
Code Representation, Extended 
Character Codes, BASIC Error 
Messages, and Programming Tit 
and Techniques 


496 Pages, 7 x 9%, Softbound 


ISBN: 0-672-46427-6 
No. 46427, $26.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 


The Waite Group’s 
Desktop Publishing Bible 
James Stocklord, Editor 


Publish high-quality documents right 
on your desktop with this “bible” that 
tells you what you need to know— 
everything from print production, 
lypography, and high-end typesetters, to 
copyright information, equipment, and 
software. 


In this collection of essays, experts 
from virtually every field of desktop 
publishing share their tips, tricks, and 
techniques while explaining both tradi- 
tional publishing concepts and the new 
desktop publishing hardware and 
software. 


Topics covered include: 


@ Publishing Basics: Traditional Print 
Production, Conventional Typography, 
Case Studies in Selecting a 
Publishing System, and a Comparison 
of Costs for Desktop and Conventional 
Systems 

@ Systems: The Macintosh, PC, MS-DOS, 
An Overview of Microsoft Windows, 
Graphics Cards and Standards, 
Monitors, Dot and Laser Printers, 
UNIX, and High-End Work Stations 

@ Sofiware: Graphics Software, Page 
Layout Software, Type Encoding Pro- 
grams, PostScript, and JustText 

@ Applications: Newsletters, Magazines, 
Forms, Comics and Cartooning, and 
Music 


480 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22524-7 
No. 22524, $24.95 


Personal Publishing with 
PC PageMaker® 
Terry M. Ulick 


Here is everything you need to know 
about PC PageMaker to design publica- 
tions. It shows you how to select and 
use type, work in multicolumn and 
multipage layouts, create graphs, and 
merge text with graphic elements. 


Hands-on instruction at the terminal, 
humerous visual examples, and a detailed 
explanation of typesetting terms pro- 
vide the information necessary to help 
the beginning to intermediate PC user 
produce attractive copy. 


Topics covered include: 


@ Assembling a Personal Publishing 
System 

@ Selecting the Right Hardware and 
Software 

@ Pages on the IBM® 

@ Electronic Page Assembly 

@ Working with Type 

@ PostScript™ and LaserJet Plus™ 
TypeStyles 

@ Formatting Type 

@ Working with PageMaker 

@ Building Master Pages 

@ Placing Elements on a Page 

@ Adding Graphic Elements 

@ Linking PageMaker Files 

@ Printing Page Files 

@ High-Volume Printing 

@ Multicolored Pages 

@ Grids and Sample Pages 


304 Pages, 7% x 9%, Softbound 
ISBN: 0-672-22593-X 
No. 22593, $18.95 


Micro-Mainframe Connection 
Thomas Wm. Madron 


Focusing on the organizational environ- 
ment, this book explores the oppor- 
tunities, technologies, and problems 
involved in implementing the transfer of 
data between the mainframe and the 
micro workstation—more comprehen- 
sively than any other book on the 
market. 


Designed to help managers and 
technical support people design and 
implement micro-mainframe networks, it 
gives complete information about 
features, facilities, and requirements, 
including cost considerations. 


Topics covered include: 


@ The Micro-Mainframe Link 

@ Features, Facilities, and Problems 
in the Micro-Mainframe Connection 

@ Local Area Networks in the 
Micro-Mainframe Connection 

@ Micros as Mainframe Peripherals: 
Mainframes as Micro Peripherals 

@ Micros and IBM® Mainframes in a 
Synchronous Network 

@ Asynchronous Devices in a 
Synchronous Network: Protocol 
Conversion 

@ File Transfer 

@ Data Extraction, Data Format, and 
Application Specific File Transfers 

@ Making the Micro-Mainframe 
Connection 


256 Pages, 7% x 9%4, Hardbound 


ISBN: 0-672-46583-3 
No. 46583, $29.95 


The Waite Group's 
Modem Connections Bible 
Curtis and Majhor 


This book describes modems, how they 
work, and how to hook ten well-known 
modems to nine name-brand computers. 
A handy Jump Table shows where to 
find the appropriate connection diagram 
and applies the illustrations to eleven 
more computers and seven additional 
modems. It also features an overview of 
communications software, an explana- 
tion of the RS-232C interface, and a 
section on troubleshooting. 


Topics covered include: 


@ Types of Modems 

M@ How Modems Work 

@ Connecting Equipment 

@ The RS-232 Connector 

W@ The Progress of a Call 

@ Full Duplex and Half Duplex Mode 

@ Types of Communications Programs 

@ Features and Uses 

@ Voice/Data Switching 

@ How to Read the Charts 

@ Jump Table 

@ Appendices: Types of Online Services 
and Costs, The RS-232C Interface, 
Further Reading, Glossary, 
Troubleshooting, Communications 
Software for Microcomputers 


192 Pages, 7% x 9%, Softbound 
ISBN: 0-672-22446-X 
No. 22446, $16.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 


The Waite Group's 
Printer Connections Bible 
Marble and House 


This book contains all the information 
necessary to make the proper connec- 
tions to get a printer printing. It focuses 
on the hardware side of connecting, 
particularly the main interface—the 
cable itself. 


Avoid hours of frustration with this 
easy-to-follow format including tables 
and diagrams, information about various 
printers, computers and software, 
printer technology, and cables and 
connectors. 


Topics covered include: 


@ Types of Printers 

@ Cable and Connector Types 

@ Soldering 

@ The ASCII Code 

@ Binary Numbers 

@ Serial and Parallel 

@ Centronics Parallel 

@ More Complex Parallel Interfaces 

w® RS-232 Serial Interface 

@ Speed Considerations in RS-232 

@ Printer Drivers 

@ Hardware versus Software 
Handshaking 

@ DIP Switches 

@ Jump Table 

@ Connection Diagrams 

240 Pages, 7' x 9%, Softbound 


ISBN: 0-672-22406-2 
No. 22406, $16.95 


The Waite Group's 
Microsoft® C Programming 
for the IBM® 

Robert Lafore 


Programmers using the Microsoft C 
compiler can learn to write useful and 
marketable programs with this entry 


to the IBM PC family of computers. 
Unlike other introductory C titles, it is 


provides special coverage of IBM 
features such as sound, color graphics 
including CGA and EGA, keyboard, 


Topics covered include: 


@ Getting Started 

@ Building Blocks 

Bi Loops 

@ Decisions 

@ Functions 

@ Arrays and Strings 

@ Pointers 

@ Keyboard and Cursor 

@ Structures, Unions, and ROM BIOS 

@ Memory and the Monochrome 
Display 

@ CGA and EGA Color Graphics 

@ Files Preprocessor 


@ Larger Programs 

@ Advanced Variables 

@ Appendices: Supplemental 
Programs, Hexadecimal Numbering, 
IBM Character Codes, and a 
Bibliography 

640 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22515-8 
No. 22515, $24.95 


level book on Microsoft C programming. 
This title is a tutorial geared specifically 


written for the Microsoft C compiler. It 


variable storage, and character graphics. 


@ Serial Ports and Telecommunications 
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The Waite Group’s 

Turbo C® Programming for 
the IBM 

Robert Lafore 


This entry-level text teaches readers the 
C language while also helping them 
write useful and marketable programs 
for the IBM PC, XT, AT, and PC/2. 


This tutorial is based on Borland’s new 
Turbo C compiler with its powerful in- 
tegrated environment that makes it easy 
to edit, compile, and run C programs. 
The author's proven hands-on intensive 
approach includes example programs, 
exercises, and questions and answers 
and covers CGA and EGA graphic 
modes. 


Topics covered include: 


@ C Building Blocks 

@ Loops 

@ Decisions 

@ Functions 

@ Arrays and Strings 

@ Pointers 

@ Keyboard and Cursor 

@ Structures, Unions, and ROM BIOS 

@ Memory and the Character Display 

@ CGA and EGA Color Graphics 

@ Files 

@® Larger Programs 

@ Advanced Variables 

@ Appendices: References, 
Hexadecimal Numbering, Biblio- 
graphy, ASCII Chart, and Answers to 
Questions and Exercises 

608 Pages, 7% x 9%, Softbound 


ISBN: 0-672-22614-6 
No. 22614, $22.95 


IBM® PC and Macintosh® 
Networking Featuring: TOPS™ 
and AppleShare™ 
Stephen L. Michel 


IBM PC and Macintosh owners and 
users who want to combine the power 
of their machines will welcome this 
complete resource for networking the 
IBM PC and the Macintosh using TOPS 
and AppleShare. 


This book details the specifics of using 
the Macintosh and the [BM PC on the 
same network, including transferring 
files, sharing printers, transporting data 
from IBM software to Mac and vice ver- 
sa, and mixing word processing and 
spreadsheet programs. 


Topics covered include: 


@ How the Macintosh and PC Really 
Differ 

@ TOPS 

@ AppleShare 

@ Coexistence 

@ Managing the Network 

@ Appendices: Glossary, ASCII 
Characters Sets, Using PostScript 
Printers 


328 Pages, 734 x 94, Softbound 


ISBN: 0-672-48405-6 
No. 48405, $21.95 


Visit your local book retailer, use the order form provided, or call 800-428-SAMS. 


HOWARD W. SAMS & COMPANY 


The Waite Group's _ 
MS-DOS Papers 
for MS-DOS Developers and Power Users 


MS-DOS Papers lets you exploit the MS-DOS operating system to its limit. Essays on 
fourteen state-of-the-art topics, written by experts and aimed at programmers and serious 
users, present the inner workings of the MS-DOS operating system, secrets of undocu- 
mented features, and tips for creating powerful new MS-DOS applications. 


You'll find advanced techniques in assembly language and C, replacement shells for the 
DOS command line, little-known details on writing safe Terminate and Stay Resident 
programs, a complete examination of device drivers, and more, including 


e A rare look at the cryptic and detailed internal structures of the MS-DOS operating 
system 

e PCnix, a UNIX-like shell replacement for MS-DOS, consisting of public domain utilities, 
batch files, and patches 

e aa techniques for using Microsoft's Macro Assembler (MASM) 5 and third-party C 
ibraries 

e Writing Terminate and Stay Resident (TSR) programs, including when to use the little- 

known INT 50h, INT 51h, INT2Fh (Multiplex Implement), and Functions 31h (Keep Process 

Call) and 34h (IN_DOS Flag Call) 

Exploring programming concepts of MS-Windows: queues, message streams, Windows 

functions, classes, regions, resources, and a complete SPY examination utility in C 

The interface between the MS-DOS operating system and device drivers, with detailed 

information about Program Segment Prefix (PSP), Memory Control Block Chain, MS-DOS 

busy flag, System File Table, Device Control! Blocks, and Current Directory Structure 

e Enhanced Graphics Adapter (EGA) programming, including control of EGA registers, 

latches, bit mask, and map mask, with listings for graphics routines written in C 

A detailed examination of serial port control, including a complete communications 

package 

e Expanded Memory Specification (EMS) versions 3.2 and 4.0, and EEMS, including bank 
switching, testing for EMM, and error code and relevant function tables 


This valuable reference presents a remarkable range of powerful techniques, insider 
shortcuts, and wizardry for the most popular operating system ever created. 


The Waite Group is a developer of computer, science, and technology books. 
Acknowledged as a leader in the field, The Waite Group creates book idess,§§ === 
finds authors, and provides development support throughout the book cycle, 
including editing, reviewing, testing, and production control for each title. 
The Waite Group has produced over 70 titles, including such best-sellers as C 
Primer Plus, MS-DOS® Developer's Guide, Tricks of the UNIX® Masters, and 
Assembly Language Primer for the IBM® PC. Mitchell Waite, president of The 
Waite Group, wrote his first computer book in 1976. Today The Waite Group 
produces 15 to 20 new computer books each year. Authors can contact The ~ >) 
Waite Group at 3220 Sacramento Street, San Francisco, California, 94115. 


$26.95/22594 ISBN: 0-672-22594-8 


HOWARD W. SAMS & COMPANY 
A Division of Macmillan, Inc. 
4300 West 62nd Street 
Indianapolis, Indiana 46268 USA 


